Markdown
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:
- The plain-text source should read naturally.
- 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)

> 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.