About Markdown

Markdown is the most widely-used lightweight markup language on the web. Created by John Gruber in 2004 with help from Aaron Swartz, it was designed to be readable as plain text while compiling cleanly to HTML. Two decades later, markdown is the lingua franca of developer documentation: every README on GitHub, every doc on GitLab, every page on Stack Overflow, every message on Slack and Discord, every note in Notion or Obsidian — all use some flavor of markdown.

CommonMark, GFM, and Other Dialects

The original 2004 spec was famously underspecified — there were over a dozen popular implementations that disagreed on edge cases. CommonMark, finalized in 2014, is a strict standard that resolves these ambiguities. Most modern parsers (cmark, markdown-it, remark) implement CommonMark.

GitHub-Flavored Markdown (GFM) is CommonMark plus a handful of common extensions: tables, task lists with checkboxes ([ ] / [x]), strikethrough with ~~, autolinking of bare URLs, and stricter handling of raw HTML. Most documentation platforms support GFM. This editor implements CommonMark plus the GFM extensions.

Markdown Syntax Reference

# H1            ## H2           ### H3
**bold**        *italic*        ~~strikethrough~~
`inline code`   [link](url)     ![alt](image.png)

> blockquote

- bullet item            1. ordered item
- nested?                2. another
  - sub-item             3. third

```js
fenced code block with language
```

| Col 1 | Col 2 |
| ----- | ----- |
| cell  | cell  |

---  (horizontal rule)

Common Pitfalls

Single newlines vs paragraphs. A common surprise: in CommonMark a single newline does not create a line break — the two lines join into one paragraph. To force a hard break, end the line with two trailing spaces or a backslash. To start a new paragraph, leave a blank line.

Lists that won't format. Markdown lists need a blank line above the first item. Some text\n- item won't render as a list — but Some text\n\n- item will.

Underscore inside identifiers. foo_bar_baz can accidentally render as italic in some parsers because the underscores are treated as emphasis markers. Most modern parsers (CommonMark, GFM) detect this case and leave intra-word underscores alone, but legacy renderers do not.

HTML sanitization. CommonMark allows raw HTML to pass through, but most platforms strip dangerous tags (<script>, <iframe>, inline on* handlers). If you rely on a specific HTML element, test on the target platform — your <details> tag may work on GitHub but be stripped on Reddit.

When to Use Markdown

• Project READMEs and CHANGELOGs — the de facto standard for open-source documentation.
• Static blog posts — Hugo, Jekyll, Gatsby, Astro, Next.js (MDX) all use markdown as the source format.
• API documentation — OpenAPI/Swagger descriptions are often markdown; tools like Docusaurus and MkDocs generate beautiful sites from markdown.
• Knowledge bases and wikis — Notion, Obsidian, Logseq, Roam, and modern company wikis all use markdown internally.
• Chat and support — Slack, Discord, and Microsoft Teams support markdown-like formatting.