Why the vocabulary matters

In short
  • Most Markdown confusion is vocabulary confusion, not syntax confusion.
  • People say "Markdown" when they mean one specific flavor, so advice that is right on GitHub is wrong in a chat box.
  • Thirty terms below, each defined in one or two sentences you can quote.
  • Flavor, renderer and CommonMark cause more trouble than the rest put together.

Markdown looks simple until two people describe the same problem in different words. One says the renderer is broken. Another says the flavor does not support it. A third points out the file is just plain text, so nothing can be broken. All three can be right at the same time, which is precisely why the words matter.

Saying Markdown when you mean one flavor

This is the pattern behind most questions that never get a good answer. Someone says "Markdown" when they mean the particular flavor their app happens to run. They then follow advice written for a different flavor, and the syntax quietly fails. The syntax was never wrong. The destination was.

Name the pieces and you can ask a question that has an answer. "Does this renderer support footnotes?" gets solved in seconds. "Why is my Markdown broken?" does not. If the format itself is still new to you, the plain-language introduction comes first and this page comes second.

What the right word saves you

  • Better searches. Searching fenced code block finds the answer. Searching "the three tick things" does not.
  • Faster help. A bug report that names the parser and the flavor gets fixed. One that says "it looks wrong" gets a follow-up question.
  • Fewer wrong turns. Knowing that tables are an extension rather than core Markdown explains why the table syntax works in one app and dies in the next.

Tip: Read a definition, then type the thing it describes into the free editor and watch the preview. A term you have used once sticks. A term you have only read does not.

Illustration of Markdown symbols paired with their names on index cards, laid out like a glossary on a desk

The three words that cause the most trouble

Three terms do most of the damage. They get used loosely in forum answers, blog posts and even official docs, and mixing them up sends people hunting for the fault in the wrong place.

Flavor: which set of rules you are writing for

A flavor, or dialect, is one particular set of Markdown rules. GitHub Flavored Markdown is a flavor. So are MultiMarkdown, Markdown Extra and the small subset Discord runs. They all agree on the core of headings, bold, lists and links. They disagree about everything above it.

Here is the trap. Someone asks "does Markdown support strikethrough?" As asked, the question has no answer. Strikethrough is a GFM feature, so the real question is which flavor the destination runs. Our answer on which Markdown flavor to write for shows how to work that out in about a minute.

Renderer: the software that decides what you see

A renderer turns parsed Markdown into the page in front of you. Two sites can support identical syntax and still look nothing alike, because each renderer brings its own styles, its own extensions and its own safety filter.

So "it works on GitHub" is a fact about GitHub, not a promise about anywhere else. GitHub runs its own renderer with its own rules, which our GitHub Flavored Markdown page covers in full. Paste the same text into a comment box somewhere else and a different renderer gets a vote, as the platform comparison shows.

CommonMark: a spec, not an app

CommonMark is often called a flavor. That is close, but slightly off. It is a specification: a precise, test-covered definition of how each rule must be parsed, published in 2014 to end years of ambiguity between competing implementations.

Nobody uses CommonMark the way they use Notion. What people mean is that their parser follows it. That matters because CommonMark is the floor almost everything modern stands on, GFM included. It settles the awkward cases like nested emphasis and stray asterisks, then leaves tables, footnotes and task lists to the flavors built above it.

How to use this glossary alongside the other pages

A glossary answers one question: what does this word mean? It is deliberately not a place to learn syntax, because a definition and a tutorial want different things from your attention. Here is how the pages split the work.

  1. Start here when a word is the blocker. Someone said delimiter row or front matter and the rest of the sentence stopped making sense.
  2. Move to the syntax reference for the map. It lists every element and points at the page that covers it properly.
  3. Work through the complete guide to learn it for real. Every element in order, with examples and the mistakes people actually make.
  4. Keep the cheat sheet open while you write. One page, every common mark, nothing to scroll past.

Terms that have a page of their own

Some entries below carry a link, because one paragraph is not enough for them. Fences and highlighting get the full treatment on code blocks. Link syntax, including the reference style, lives on links. Markers and their notes are on footnotes. The definition tells you what a thing is; those pages tell you how to use it.

Same word, different behaviour per app

The vocabulary is shared, the support is not

Nearly every app borrowed GitHub's words. Task list, strikethrough, pipe table and code fence mean the same thing in Notion, Obsidian, Reddit and Discord. What changes is whether the app does anything with them. Chat tools in particular support a small subset and ignore the rest without a word.

Watch out: An unsupported element rarely shows an error. It shows your raw punctuation, or nothing at all. When something renders as literal text, assume it is unsupported before you go hunting for a typo.

Two pairs people get backwards

  • Parser and renderer. The parser reads your text and works out the structure. The renderer decides how that structure looks. A table that never appears is usually a parser limit; ugly spacing is usually the renderer.
  • File and format. A .md file is plain text with a label on it, as the note on the .md extension explains. Rename it to .txt and nothing changes except which apps offer to preview it.

That is the whole reason this glossary keeps definitions short and separate from support tables. A word means one thing. Whether your app honours it is a different question, and the platforms hub is where that one gets answered.

Every term, defined

Anchor (slug)
An anchor is the link target a renderer builds from a heading, and the slug is the short lowercase text it uses as the id. GitHub turns the heading Getting Started into the slug getting-started, so a URL ending in #getting-started jumps straight to it. Read the full answer →
ATX heading
An ATX heading is a heading written with one to six hash marks at the start of a line, such as ## Setup. It is the standard heading style and works in every Markdown flavor. Read the full answer →
Blockquote
A blockquote is a quoted passage marked by a greater-than sign at the start of each line. Renderers usually show it indented, with a coloured bar down the left edge. Read the full answer →
CommonMark
CommonMark is a strict specification of Markdown, published in 2014, that defines exactly how every rule must be parsed. It is the shared base that most modern flavors, including GitHub Flavored Markdown, are built on. Read the full answer →
Delimiter row
The delimiter row is the line of dashes and pipes under a table header, and it is what tells the parser the block is a table at all. A colon at one or both ends of a segment sets that column to left, right or centre alignment. Read the full answer →
Escaping
Escaping means putting a backslash in front of a character so Markdown prints it instead of reading it as formatting. It is how you show a literal asterisk, hash mark or underscore in your text. Read the full answer →
Fenced code block
A fenced code block is a block of code wrapped in a line of three backticks above it and three backticks below it. Everything between those fences is shown exactly as typed, and a language name after the opening fence switches on syntax highlighting. Read the full answer →
Footnote
A footnote is a small marker in the text that links to a note collected at the bottom of the page. It is an extended feature, so it works on GitHub and in Obsidian but not in every Markdown app. Read the full answer →
Front matter (YAML front matter)
Front matter is a block of metadata at the very top of a Markdown file, fenced by three dashes above and below. It usually holds YAML fields such as title, date and tags, which the publishing tool reads instead of printing. Read the full answer →
GitHub Flavored Markdown (GFM)
GitHub Flavored Markdown, usually shortened to GFM, is GitHub's own version of Markdown. It adds tables, task lists, strikethrough and automatic links on top of the CommonMark base, and it is the dialect most other tools copy. Read the full answer →
Hard line break
A hard line break forces a new line inside the same paragraph. You make one by ending the line with two spaces, or with a backslash in most modern parsers, because a single press of Enter is ignored. Read the full answer →
Inline code
Inline code is a short piece of code wrapped in single backticks inside an ordinary sentence. It renders in a monospace font, and no Markdown formatting is applied to anything inside it. Read the full answer →
Inline HTML
Inline HTML is raw HTML written directly inside a Markdown file. Many parsers pass it through untouched, which is how people add things Markdown has no syntax for, but stricter sites strip it out for safety. Read the full answer →
Loose list and tight list
A tight list has no blank lines between its items, and a loose list has at least one. The difference is visible because a renderer wraps every item of a loose list in a paragraph, which adds extra spacing. Read the full answer →
Markdown flavor (dialect)
A flavor, also called a dialect, is one particular set of Markdown rules, such as GitHub Flavored Markdown or MultiMarkdown. Flavors agree on the core syntax and differ on the extras like tables, footnotes and task lists. Read the full answer →
.md extension
The .md extension marks a plain text file whose contents are written in Markdown. The longer .markdown means the same thing, and neither changes the file itself, because an extension only tells apps how to treat it. Read the full answer →
Mermaid
Mermaid is a text syntax for diagrams that some sites render from a code block labelled mermaid. GitHub, GitLab, Notion, Obsidian and the editor on this site support it, while a plain Markdown parser just shows the code. Read the full answer →
Pandoc
Pandoc is a free command line tool that converts documents between formats, including Markdown to Word, LaTeX, EPUB and PDF. It is the usual answer once a browser based converter runs out of road.
Parser
A parser is the part of a program that reads your Markdown text and works out what each mark means. It builds a structure of headings, lists and paragraphs, which the renderer then turns into HTML. Read the full answer →
Pipe table
A pipe table is the standard Markdown table, with cells separated by vertical bar characters and a delimiter row under the header. Tables are an extension rather than core Markdown, so a few strict parsers ignore them. Read the full answer →
Plain text
Plain text is text stored as characters only, with no hidden formatting data attached. Markdown files are plain text, which is why they open in any editor and work cleanly with version control. Read the full answer →
Renderer
A renderer is the software that turns parsed Markdown into what you finally see, usually HTML on a page. Two sites can support identical syntax and still look nothing alike, because each renderer applies its own styles and rules. Read the full answer →
Sanitiser
A sanitiser is a filter that strips unsafe HTML, such as script tags, before Markdown is published. It explains why raw HTML that works in your local editor can quietly vanish on a public site. Read the full answer →
Setext heading
A Setext heading is an older heading style that underlines the text with equals signs for level one, or dashes for level two. Only those two levels exist, which is why hash mark headings are preferred today. Read the full answer →
Static site generator
A static site generator is a tool that turns a folder of Markdown files into a finished website of plain HTML pages. Hugo, Jekyll, Eleventy and Astro are common examples.
Strikethrough
Strikethrough is text with a line through it, written with two tildes on each side. It comes from GitHub Flavored Markdown, so it works on GitHub, Reddit and Discord but not in the original specification. Read the full answer →
Syntax highlighting
Syntax highlighting is the colouring of code by language, so keywords, strings and comments stand out. You switch it on by writing the language name straight after the opening backticks of a fenced code block. Read the full answer →
Task list
A task list is a list whose items start with square brackets that are either empty or hold an x, which renders as a checkbox. It is a GitHub Flavored Markdown feature and is widely copied by note taking apps. Read the full answer →
WYSIWYG
WYSIWYG stands for what you see is what you get, the style of editor where text looks formatted as you type it. Markdown is the opposite by design: you type marks in plain text and see the formatted result after it is rendered. Read the full answer →

Frequently Asked Questions

What is a fenced code block?

A fenced code block is code wrapped in three backticks on the line above and three on the line below. Everything between the fences is shown exactly as typed, with no bold, italics or links applied. Add a language name after the opening fence, like python, and most renderers colour the code for you. The code blocks page covers fences, indented blocks and highlighting in full.

What does CommonMark mean?

CommonMark is a specification, not an app or a product. It was published in 2014 to define exactly how each Markdown rule must be parsed, backed by hundreds of tests, because the original 2004 description left too much open to interpretation. When someone says a tool is CommonMark compliant, they mean its parser follows that spec. Most modern flavors, GitHub's included, build on it.

Is a Markdown flavor the same as a renderer?

No, and mixing them up is the most common mistake here. A flavor is a set of rules, such as GitHub Flavored Markdown. A renderer is the software that applies those rules and paints the result on screen. One flavor can be implemented by many renderers, which is why the same syntax can be supported yet look different on two sites. Our page on GFM shows both sides of that.

Which Markdown terms should a beginner learn first?

Five carry most of the weight: flavor, renderer, fenced code block, plain text and .md file. With those you can read almost any answer online and know which part applies to you. Learn the rest as you meet them. The cheat sheet covers the marks themselves, and you can test each one in the editor as you go.

Keep learning

Markdown Syntax Reference

Every element on one map, with the page that covers each in depth.

Markdown Cheat Sheet

Every common mark on a single page, built to keep open while writing.

GitHub Flavored Markdown

The dialect behind tables, task lists and strikethrough, explained.

Try the Editor

Open Editor