Topolearn

Learn Markdown

Plain-text formatting for READMEs, docs, notes and comments

13 lessons · 2 hours · 4 levels · covers Markdown CommonMark 0.31.2 + GFM

Markdown turns plain text with a few punctuation conventions into formatted HTML. It is the format of READMEs, GitHub issues and pull requests, documentation sites, chat apps and note-taking tools, and CommonMark plus GitHub Flavored Markdown define exactly how it is parsed.

Sign in free to track progressOfficial docs ↗

How deep do you want to go?

1. EssentialsRead and write simple code, do the everyday basics3 lessons · 26 min in total
2. PracticalUse it productively at work, with the usual idioms7 lessons · 1 hour in total
3. AdvancedThe less common features, performance and trade-offs10 lessons · 2 hours in total
4. ExpertInternals and the edge cases experts know13 lessons · 2 hours in total

The Markdown tree

MarkdownParagraphs, line breaks and emphasisParagraphs, linebreaks and emphasisHeadings and listsHeadings and listsLinks and imagesLinks and imagesCode spans and code blocksCode spans and codeblocksBlockquotes, rules and escapingBlockquotes, rulesand escapingTables (GFM)Tables (GFM)Task lists, strikethrough, footnotes, alertsTask lists,strikethrough, foot…
Essentials and Practical shown (7 of 13 lessons); the full list is below. Click a lesson to read it.

All 13 lessons, in order

Writing basics

  1. Paragraphs, line breaks and emphasis · Essentials · 8 min

    Separate paragraphs with blank lines, force line breaks with a trailing backslash, and use *italic*, **bold** and `code` inline.

  2. Headings and lists · Essentials · 10 min

    Structure documents with # headings, and write bullet lists with - and numbered lists with 1., nesting them by indentation.

  3. Links and images · Essentials · 8 min

    Write inline links [text](url "title"), images ![alt](src), autolinks <https://...>, and links to sections and files in a repository.

Code, quotes and tables

  1. Code spans and code blocks · Practical · 10 min

    Show code inline with backticks and in fenced blocks with ``` and a language tag for highlighting; know the indented-block form and how to show backticks.

  2. Blockquotes, rules and escaping · Practical · 8 min

    Quote text with >, separate sections with ---, and escape characters that would otherwise be read as Markdown.

  3. Tables (GFM) · Practical · 10 min

    Build tables with pipes and a --- delimiter row, align columns with colons, and know the limits of Markdown tables.

  4. Task lists, strikethrough, footnotes, alerts · Practical · 10 min

    Use GitHub's extras: - [ ] task lists, ~~strikethrough~~, bare-URL autolinks, footnotes, alerts like > [!NOTE], and @mentions and #references.

Flavours and tooling

  1. Reference links and heading anchors · Advanced · 10 min

    Keep paragraphs readable with reference-style links [text][id] and definitions at the bottom, and link reliably to headings.

  2. HTML inside Markdown · Advanced · 10 min

    Mix raw HTML into Markdown for what it can't express (details/summary, image sizes, anchors), and understand blank-line rules and sanitization.

  3. Flavours, front matter and tooling · Advanced · 12 min

    Know CommonMark, GFM and other flavours, YAML front matter, diagrams and math blocks, MDX, and the linters and formatters that keep Markdown consistent.

How it's parsed

  1. How CommonMark parses: blocks, then inlines · Expert · 15 min

    Understand CommonMark's two-phase parse: block structure (containers, leaf blocks, lazy continuation) first, then inline parsing of each paragraph and heading.

  2. List edge cases: indentation, tight and loose · Expert · 12 min

    Master CommonMark's list rules: content indentation, the four-space trap, tight versus loose lists, starting numbers and when a list interrupts a paragraph.

  3. Emphasis rules: delimiter runs and flanking · Expert · 12 min

    How CommonMark decides whether * and _ open or close emphasis: flanking delimiter runs, the intraword underscore rule and the rule of 3.