Markdown

Markdown is a lightweight markup language for writing structured documents while keeping the source readable as plain text. It shows up everywhere: dev docs, READMEs, issues, blogs, notes.

1. About Markdown

John Gruber designed Markdown in 2004 with Aaron Swartz. The goal was twofold:

1. The plain-text source should read naturally.
2. It should convert to HTML smoothly.

The original spec was short and ambiguous in places. The same syntax was interpreted differently across implementations, so in 2014 CommonMark appeared as a standardization effort. Building on top of it, GitHub added tables, task lists, and autolinks to define GFM (GitHub Flavored Markdown), which became the de facto user standard.

2. CommonMark and GFM

Item	CommonMark	GFM
Base syntax (headings, emphasis, lists, links)	Defined	Inherits
Tables	None	Yes
Task lists (- [ ])	None	Yes
Strikethrough (~~text~~)	None	Yes
Auto URL linking	Weak	Strong
Code block language hint	Yes	Yes

GitHub, GitLab, Bitbucket render GFM, so READMEs are usually written assuming GFM.

3. Headings, emphasis, lists

# H1
## H2
### H3

*italic* or _italic_
**bold** or __bold__
~~strikethrough~~  (GFM)

- Item A
- Item B
  - Nested

1. First
2. Second

4. Links, quotes, code

[link text](https://example.com)
![alt text](path/to/image.png)

> Quotes are indented one level.

Inline code uses `code`. Block:

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

Tagging a code block with a language name turns on syntax highlighting in GitHub, VS Code, and most static site generators. To intentionally render plain text, use text or leave it empty.

5. Tables, task lists (GFM)

| Field | Value |
|---|---|
| Name | alice |
| Age | 30 |

Use colons to align — |:---| left, |---:| right, |:---:| center.

- [x] Completed item
- [ ] Open item

6. Why language hints matter

• Syntax highlighting — readability is clearly better.
• GitHub search and rendering — some tools index only by language metadata.
• Conversion friendliness — pandoc, MDX, and similar tools produce more accurate output.
• AI tooling — code extraction and analysis become more accurate with explicit language info.

7. Why README is markdown

READMEs were plain text since Unix days. After GitHub launched in 2008 and started auto-rendering README.md at the repository root as HTML, virtually every host followed the same convention. The name README is just convention, but it lives on the auto-render list (README.md, README.markdown, Readme.md).

8. Limits and supplements

Markdown is intentionally simple. The following areas are weak or missing:

• Fine-grained styling (fonts, colors, spacing).
• Complex layouts (multi-column, sidebars).
• Dynamic components.
• Footnotes/references (only in some extensions).
• Metadata (the front-matter convention).

Tool	What it adds
MDX	React/JSX components inside Markdown.
AsciiDoc	Richer document markup. Used by O'Reilly.
reStructuredText	The Python (Sphinx) standard. Stricter and more extensible.
Pandoc	A converter between virtually every markup.
Front matter (YAML · TOML)	Metadata block at the top of the file (Jekyll, Hugo, Astro).

---
title: Document title
date: 2026-04-25
tags: [markdown, docs]
---

# Body starts

9. Preview tooling

Task	macOS · Linux	Windows
VS Code preview	Cmd+K V	Ctrl+K V
pandoc conversion	pandoc README.md -o README.html	Same
Terminal rendering	glow README.md or mdcat	glow (Scoop, winget)

10. Common pitfalls

Code-block indentation — four-space indents also create code blocks. Sometimes text under a list accidentally becomes code.

Backticks inside inline code — wrap with two backticks to allow a literal backtick inside.

Line breaks — pressing Enter without a blank line continues the same paragraph. Force a line break with two trailing spaces + Enter or an empty line.

HTML tags pass through — some renderers strip certain tags for safety (GitHub blocks <script>).

To use | as text inside a table, escape with \|.

Headings without blank lines above or below may not render as headings in some implementations.

Closing thoughts

Markdown is the simplest markup, so the learning curve is near zero. Its strength comes through with GFM tables/tasks/autolinks + front matter + language-tagged code blocks all in place. When fine layout becomes necessary, MDX or AsciiDoc step up a level.

Next

• text-encoding-line-endings
• first-terminal-day

CommonMark Spec · GFM Spec · Daring Fireball Markdown · MDX · Pandoc for reference.