Why this page exists
You've noticed it already: a table that renders on GitHub shows up as pipe soup somewhere else, and Slack turns your single stars into something unexpected. That's not markdown being broken - it's markdown being a family of dialects. Knowing the family tree tells you instantly what will work where, and the export tools mean you're never locked into any one of them.
The flavor map: one family, many dialects 6 min read
John Gruber's 2004 original left edge cases undefined, so every implementer filled the gaps their own way. Two decades later the family looks like this:
Self-studyCore vs extended: the line that predicts everything3 min▶
Every "will this render there?" question comes down to one line:
- Core (works virtually everywhere): headings, paragraphs, line breaks, bold, italic, blockquotes, ordered and unordered lists, inline code, indented code, horizontal rules, links, images - your Session 1-2 basic set. This is what CommonMark standardized.
- Extended (app-by-app): tables, fenced code blocks with syntax highlighting, footnotes, heading IDs, definition lists, strikethrough, task lists, emoji shortcodes, highlight, subscript, superscript, automatic URL linking - the Markdown Guide's extended-syntax list.
- Platform extras (one app only): GitHub's alerts, mentions, and color chips; Obsidian's wikilinks; each tool's party tricks live at this layer.
Self-studyWhy CommonMark exists2 min▶
The 2004 original shipped as a description plus a script, and reasonable people read the description differently. Does a star inside a word emphasize? How many spaces nest a list? For years, every implementation answered differently - same file, different rendering.
CommonMark fixed this by writing an unambiguous spec for the shared core, with a giant test suite anyone can implement against. That's why your Session 1 elements behave identically across serious apps today: most modern implementations, GitHub's included, build on CommonMark and add extras on top. The standard is the peace treaty; the flavors are what each app negotiated extra.
Where each flavor lives 4 min read
Same syntax, different habitats. Here's what to expect from the apps you'll actually meet.
Self-studyThe habitat table3 min▶
| App | What it speaks | Watch out for |
|---|---|---|
| GitHub | GFM - the full extended set you learned in Sessions 2-3 | Some extras are context-bound: color chips render in issues/PRs only, footnotes skip wikis |
| Notion | Understands markdown as you type (# then space, ** pairs) and on paste/import | It converts your markdown into its own blocks - what you export back may not match keystroke for keystroke |
| Obsidian | Close to GFM on files on your disk | Adds its own extras like wikilinks that won't travel to other apps |
| Slack / Discord | Markdown-ish shorthand: *, `, > work in spirit | Not real markdown - no headings in Slack messages, and details differ between the two. Chat formatting, not documents |
The pattern: document tools sit near GFM; chat tools borrow the punctuation without the spec. Your core elements survive almost everywhere; everything else deserves a ten-second test.
Self-studyThe "some processors" shelf2 min▶
Three extended elements exist in the official inventories but render only on some processors - the Markdown Guide flags each one. File under "test first":
- Definition lists: a term on one line, : definition on the next. Markdown Extra territory; GitHub READMEs don't render them.
- Highlight: ==marked text== for a highlighter effect - Obsidian yes, GitHub no.
- Sub/superscript: ~sub~ and ^super^ as syntax in some processors; on GitHub use the HTML tags <sub> and <sup> from Session 3 instead.
The ten-second test: before relying on any fancy element in a new app, type a one-line sample and preview it. Ten seconds of testing beats an hour of "why is my published page full of equals signs".
Export: markdown to anything 5 min read
Because a .md file is plain text with a known grammar, converters can turn it into almost any document format. This is markdown's endgame: write once, publish anywhere.
Self-studyPandoc: the universal converter3 min▶
Pandoc (pandoc.org, free, open source) converts between dozens of document formats. The basic form, straight from its getting-started guide:
A real Word document: your headings become Word headings, lists become lists, tables become tables. Pandoc infers both formats from the file extensions - swap .docx for .html and you get a web page instead.
- The -o flag names the output; the extension picks the format. Add -s for a standalone file with a proper header when making HTML.
- PDF needs one extra: pandoc's guide notes that PDF output requires a LaTeX engine installed (MacTeX, MiKTeX, or texlive). With it: pandoc page.md -o page.pdf.
- No terminal, no problem: plenty of web-based md-to-docx converters do the same one file at a time - fine for the occasional export.
Self-studyFrom README to website: static site generators2 min▶
- The idea: a static site generator takes a folder of .md files and builds a full website - navigation, theme, search. You write markdown; it does web design.
- Closest to home: GitHub Pages can publish a repo as a website, with Jekyll as its classic engine - meaning the markdown skills from this course are literally one settings page away from being a personal site.
- Names to recognize: MkDocs (documentation sites) and Docusaurus (developer docs) - both markdown-in, website-out. When a team's docs site looks suspiciously nice, one of these is usually underneath.
Self-studyWhen to leave markdown2 min▶
Honest boundaries: markdown is for structured writing, not layout design.
- Heavy layout: multi-column spreads, precise image placement, pixel-perfect brochures - that's a design tool's job. Markdown has no opinion about where things sit on a page.
- Print typography: exact fonts, margins, and page breaks for print belong to Word, InDesign, or LaTeX. Pandoc can hand your content over; the polish happens there.
- The healthy split: draft and store the content in markdown (portable, versionable, future-proof), export to the fancy format last. Content in markdown, layout at the end - you keep the source, they get the gloss.
Export your page, watch what survives ◐ 10 min hands-on
Grab the raw markdown of your profile README (on GitHub: open README.md, the Raw button shows the plain text - copy it all).
Convert it to a Word document: paste it into any web-based markdown-to-docx converter and download the result, OR if you're comfortable in a terminal, install pandoc and run pandoc README.md -o README.docx.
Open the .docx and audit it against the core-vs-extended line: headings, lists, links, and tables should have survived as real Word structures. What happened to your badges, emoji shortcodes, collapsibles, and Mermaid block?
Write the answer down as one takeaway sentence - you've just measured exactly where your document's portability ends, which is the whole lesson of this page.
Three questions before you go 🎯 ◐ 90 seconds
1 · What's the relationship between CommonMark and GFM?
CommonMark nails down the shared basics precisely; GitHub Flavored Markdown extends that base with the Session 2-3 features.
2 · Which of these are EXTENDED syntax (app-dependent), not core?
B and C are the CommonMark core - safe everywhere. The extended set works on GitHub but deserves a test-first anywhere else.
3 · What does pandoc do?
Pandoc is the universal document converter: format inferred from extensions, -o names the output, PDF needs a LaTeX engine installed.
Official sources covered
This page draws on the flavor and export notes across markdownguide.org (getting-started + extended syntax), the framing at commonmark.org, and the getting-started guide at pandoc.org.