Andrew Mercer

Comprehensive Guide to Markdown

What It Is

Markdown is a lightweight markup language for writing formatted text using plain, readable syntax that compiles to HTML. Created by John Gruber in 2004, its goal was for a document to be readable as-is, even before rendering. It's the default format for READMEs, documentation sites, GitHub/GitLab issues and PRs, static site generators (Hugo, Jekyll, MkDocs), and note-taking tools.

There's no single official spec owned by one governing body. The practical standard most tooling follows today is CommonMark, with GitHub Flavored Markdown (GFM) layered on top for extras like tables and task lists.

Core Syntax

Headings

# H1
## H2
### H3
#### H4

Alternate (setext) style exists for H1/H2 only, but is rarely used:

H1 Title
========

H2 Title
--------

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold italic***
~~strikethrough~~

Paragraphs and line breaks

Paragraphs are separated by a blank line. A single newline is usually collapsed into a space — to force a line break within a paragraph, end the line with two trailing spaces, or use <br>.

Lists

Unordered:

- Item one
- Item two
  - Nested item
* Also valid
+ Also valid

Ordered:

1. First
2. Second
3. Third

The actual numbers you write mostly don't matter for rendering (most parsers auto-number), but keeping them accurate helps readability of the raw source.

[link text](https://example.com "optional title")
![alt text](https://example.com/image.png)

<!-- Reference-style, useful for reused links -->
[link text][ref]

[ref]: https://example.com

Code

Inline: `code`

Fenced blocks with optional language for syntax highlighting:

```python
def hello():
    print("hi")
```

Indented code blocks (4 spaces) also work in classic Markdown but are less common now that fenced blocks are near-universal.

Blockquotes

> A quoted line.
> Continues here.
>
> > Nested blockquote.

Horizontal rule

---
***
___

Any of the three (three or more of the same character) works.

GitHub Flavored Markdown (GFM) Extras

Tables:

| Name    | Role      |
|---------|-----------|
| Andrew  | Platform  |
| Alice   | SRE       |

Alignment with colons:

| Left | Center | Right |
|:-----|:------:|------:|
| a    | b      | c     |

Task lists:

- [x] Done
- [ ] Not done

Strikethrough: ~~text~~

Autolinks: GitHub auto-links bare URLs and shorthand references like user/repo#123 or @username — this is a GitHub-specific rendering feature, not part of CommonMark.

Footnotes (supported by GFM and many static site generators, not core CommonMark):

Here's a claim.[^1]

[^1]: This is the footnote text.

Extended Ecosystem Variants

Beyond CommonMark/GFM, you'll encounter:

  • MDX — Markdown that allows embedding JSX/React components, used by tools like Docusaurus.
  • Pandoc Markdown — a very extended dialect supporting citations, definition lists, and complex academic document features, used as an intermediate format for converting to/from dozens of other document types.
  • R Markdown — embeds executable R code chunks, used in data science reporting.

Knowing which flavor a given tool expects matters — a feature that renders fine on GitHub (footnotes, task lists) may not render at all on a strict CommonMark-only parser.

Gotchas

  • Flavors differ. The single biggest source of "why doesn't this render" is assuming GFM features work everywhere.
  • Blank lines around block elements matter. A list immediately following a paragraph with no blank line between them can fail to parse as a list start in some parsers.
  • Line breaks require two trailing spaces or <br> — invisible whitespace is an easy thing to lose in version control or when text is auto-formatted.
  • Escaping — use \ before literal *, _, `, #, etc. when you don't want Markdown syntax interpreted: \*not italic\*.
  • Raw HTML passes through in most Markdown flavors untouched. This is powerful (you can drop in a <details> block for collapsible sections) but also a common source of broken rendering from unclosed tags.
  • Nested lists and indentation — mixing tabs and spaces, or using inconsistent indent widths, can break nesting in a way that's hard to spot visually.

Tools

  • CommonMark spec/reference — the closest thing to a canonical spec, with an online "try it" dingus
  • markdownlint — CLI/editor linter for consistent style (available as a VS Code extension too)
  • Pandoc — universal document converter; turns Markdown into docx, PDF, HTML, LaTeX, and back
  • Prettier — can auto-format Markdown alongside code for consistent style in a repo