# please.md ### clankers speak fluent markdown. humans, catch up while you still can. one page · seven flavors · [curl it](#curl) · [raw.md](/raw.md) ## hello world one format your CEO writes the funding memo in, and the LLM replacing them drafts the layoffs in. esperanto that worked. three symbols and you're 80% there: `#` makes big. `**` makes bold. `-` makes list. the rest is more of that. in seven flavors, because *engineers*. ## why markdown {#why} - **plain text, forever.** your AI startup is one cognition acquisition away from a $250M wind-down. markdown is letters; nobody acqui-hires letters. - **every app speaks it.** even the one your CEO vibe-coded in 4 hours and announced as a series A. - **clankers eat it.** LLMs trained on more markdown than github has READMEs. saves your CTO the "agent swarm" line item. - **word™ stops fighting you.** you typed `- thing`, you got `- thing`. no recall™ leaking your unsent draft in next quarter's CVE. groundbreaking. ## heads up {#catch} "markdown" is several markdowns in a trench coat. - [**CommonMark**](#basics) is the standard. everything else builds on it. - **GitHub** adds tables, task lists, strikethrough. calls it [**GFM**](#extended). what every README actually uses. - [**Slack**](#slack-mrkdwn) decided one asterisk means bold and named their version **mrkdwn**. yes, without the 'a'. probably an A/B test that won. - [**Reddit**](#reddit-snudown) has `>!spoilers!<` and `^superscript`. because reddit. - [**Discord**](#discord) has `||spoilers||` and `<@mentions>`. same energy, different syntax. - [**Notion**](#notion) isn't really markdown. it imports some, exports some, loses toggles on the way out. it's fine. every syntax here wears a badge: {CM} {GFM} {RDT} {DIS} {SLK} {NTN} {EXT} writing for github? stay in {CM} + {GFM}. writing for slack? stop typing `#`. nothing will happen. writing for an LLM? any of them. clankers are omnivores. writing elsewhere? check the badges. ok. let's go. --- ## the 8 things you already know Source on the left, rendered on the right. This is 90% of the markdown you'll ever write. ### headings {CM} ```md # Page title ## Section ### Subsection ``` ### emphasis {CM} {#emphasis-taste} ```md *italic* or _italic_ **bold** or __bold__ ***both*** at once ``` ### lists {CM} ```md - apples - pears - oranges 1. first 2. second 3. third ``` ### links {CM} ```md [please.md](https://please.md) ``` ### inline code {CM} ```md Use `git status` before committing. ``` ### code blocks {CM} ````md ```js console.log("hello"); ``` ```` ### blockquotes {CM} {#blockquotes-taste} ```md > One file. > Legible to humans and machines. ``` ### horizontal rule {CM} ```md --- ``` --- ## the basics · CommonMark {#basics} This is the standard. If a tool claims "markdown support," it supports at least this. Grouped by [block](https://spec.commonmark.org/0.31.2/#blocks-and-inlines) vs [inline](https://spec.commonmark.org/0.31.2/#inlines), same way the spec does it. ### blocks Blocks are the big boxes: paragraphs, lists, code blocks, headings. They own whole lines. #### ATX headings {CM} Hash marks. The number of `#` equals the level. Trailing hashes are optional. ```md # H1 ## H2 ### H3 #### H4 ##### H5 ###### H6 ## Close me ## ``` #### Setext headings {CM} Two levels only. Underline the heading text with `=` (H1) or `-` (H2). Great when you want the source to look like a document. ```md Big Title ========= Medium Title ------------ ``` #### paragraphs & line breaks {CM} {#paragraphs} Blank line between paragraphs. Two trailing spaces (or a backslash) at the end of a line = hard break. A single newline in source is a soft break, which renders as a space. ```md This is one paragraph. This line continues the paragraph, newline becomes a space. New paragraph here. Hard break with two spaces: next line appears below. Hard break with a backslash:\ also works. ``` #### blockquotes {CM} Prefix with `>`. Lazy continuation is fine: subsequent lines without `>` still belong to the quote as long as they're not blank. ```md > This is a quote. > It can span multiple lines. lazy continuation works too. > Quotes can also > > > nest. ``` #### unordered lists {CM} Any of `-`, `*`, `+`. Pick one and stick with it. Indentation controls nesting. ```md - apples - pears - anjou - bosc - oranges ``` #### ordered lists {CM} Start with a number + `.` or `)`. The numbering renders from the first one. You can write `1. 1. 1.` and they render as 1, 2, 3. You can also start at any number. ```md 1. first 2. second 3. third 7. starts at seven 8. eight ``` #### thematic break {CM} Three or more `-`, `*`, or `_` on their own line. All three are equivalent. ```md --- *** ___ ``` #### indented code blocks {CM} Four leading spaces (or a tab). The old-school way. Fenced blocks are almost always nicer. ```md function hello() { return "world"; } ``` #### fenced code blocks {CM} Three or more backticks (or tildes). Add an info string for the language hint. Renderers use it for syntax highlighting. ````md ```js const greet = (name) => `hello, ${name}`; ``` ~~~python def greet(name): return f"hello, {name}" ~~~ ```` #### HTML blocks {CM} Raw HTML passes through. Useful for things markdown can't express: details elements, custom classes, iframes. ```md
Click to expand Hidden paragraph.
``` > **Note.** GFM on GitHub filters dangerous tags ({GFM} disallowed raw HTML). Renderers in security-sensitive contexts strip HTML entirely. #### link reference definitions {CM} {#link-refs} Define a link once, use it by name. Keeps prose clean when you reference the same URL many times. ```md See the [spec][cm] and the [parser][js]. [cm]: https://spec.commonmark.org/0.31.2/ [js]: https://github.com/commonmark/commonmark.js "CommonMark reference implementation" ``` --- ### inlines Inlines live inside a line: emphasis, code spans, links, images, the stuff that decorates text. #### emphasis & strong {CM} {#emphasis} One `*` or `_` = italic. Two = bold. Three = both. CommonMark prefers `*` inside words because `_` inside words doesn't work the way you'd expect (`foo_bar_baz` is just text). ```md *italic* and _italic_ **bold** and __bold__ ***both*** or ___both___ Emphasis inside_words_ does not work with underscores. Use *asterisks* inside-words instead. ``` #### code spans {CM} Backticks around code. If your code contains a backtick, use more backticks on the outside. ```md Run `git status` to see changes. Two backticks around ``a `backtick` inside``. ``` #### inline links {CM} `[text](url)`. Title is optional and goes in quotes after the URL. ```md [please.md](https://please.md) [with title](https://please.md "a cheat sheet you can send your boss") ``` #### reference links {CM} Defined elsewhere with a label. Three flavors: full, collapsed, shortcut. ```md Full: [text][label] Collapsed: [label][] Shortcut: [label] [label]: https://please.md ``` #### autolinks {CM} Wrap a URL or email in angle brackets. No `[text]` needed. Note: GFM extends this to work WITHOUT angle brackets ({GFM} extended autolinks, see next section). ```md ``` #### images {CM} Same as links, with a leading `!`. Alt text goes in the brackets. ```md ![alt text](https://please.md/hero.png) ![alt text](https://please.md/hero.png "title on hover") ![by reference][img] [img]: https://please.md/hero.png ``` #### hard & soft line breaks {CM} {#line-breaks} Soft break = single newline in source → rendered as a space. Hard break = two trailing spaces or a backslash → `
`. ```md line one line two (soft break, joined with a space) line one with hard break line two (on a new line) line one with backslash hard break\ line two ``` #### raw HTML {CM} Inline HTML tags are kept as-is by spec-compliant parsers. Again, sandboxed contexts strip them. ```md Click Ctrl+C to copy. This is red text. ``` #### entities & numeric refs {CM} {#entities} HTML entities work: `©`, `&`, `©`, `©` all render as their character. ```md Copyright © 2026 & so on. © © ``` #### backslash escapes {CM} Prefix an ASCII punctuation character with `\` to disable its markdown meaning. ```md \*not italic\* \# not a heading \[not a link](nope) ``` --- ## the extended version · GitHub Flavored Markdown {#extended} GFM is what GitHub renders. It's CommonMark plus five additions. If you're writing a README, a PR description, or an issue comment, this is your set. ### tables {GFM} Pipe-delimited. The second row is the delimiter: hyphens, with optional colons for alignment. Outside pipes are optional. The columns don't need to line up visually, but prettier source is prettier source. ```md | left | center | right | | :----- | :----: | ----: | | apples | 3 | $1.20 | | pears | 7 | $0.80 | | plums | 12 | $2.00 | ``` Escape a literal pipe inside a cell with `\|`. ```md | command | does | | ------- | ------------------- | | `a\|b` | pipes `a` to `b` | ``` ### task lists {GFM} Checkboxes in lists. Useful for issue templates, PR checklists, todo dumps. ```md - [x] wake up - [x] coffee - [ ] ship the feature - [ ] nap ``` Nest them like any list: ```md - [ ] ship please.md - [x] write the pitch - [x] write the basics - [ ] deploy ``` ### strikethrough {GFM} Two tildes. One tilde is not enough (unless you're on Slack, see dialects). ```md ~~old plan~~ new plan ``` ### extended autolinks {GFM} CommonMark needs `<...>` around URLs. GFM auto-links bare URLs, `www.` domains, and email addresses. No angle brackets required. ```md Visit https://please.md or www.please.md or email hi@please.md ``` ### disallowed raw HTML {GFM} Not a syntax, a safety filter. GitHub silently strips `