Markdown Flavors

By the Syncfusion DevTutorials team · Last updated October 20, 2026

Render one README as CommonMark, as GitHub Flavored Markdown and on a docs site. Learn the four layers of Markdown, what GFM adds, which features are platform extensions, what each one falls back to, and how to write a file that works everywhere.

One README, Three Different Pages

The order-support README uses a few handy features: a task list, a footnote, a warning box and a link written as a plain web address. On GitHub, it looks great. The same file is also shown on the team's docs site, and inside an internal tool.

The same file in three places

# Order Support

> [!WARNING]
> Refunds over ₹5,000 need a manager's approval.

Status page: https://status.example.com

## Release 2.4

- [x] Fix refund rounding
- [ ] Add order search

Refunds take 5 days.[^bank]

[^bank]: Bank transfers can take longer.

Press the three buttons at the top of the box, one after another: CommonMark, GitHub (GFM) and Docs site. Or open the Compare tab to see all three side by side, with the ones that differ from GitHub marked.

• In CommonMark, the checkboxes are [x] text, the footnote is [^bank] text, and the web address is not a link.
• In GitHub (GFM), the checkboxes, footnote and link all work. The warning is a plain quote that starts with [!WARNING].
• On the Docs site, everything works, and the warning is a coloured box.

One file, three results. Each app speaks a slightly different flavour of Markdown. In this lesson, you will learn the layers that make up those flavours, and how to write a file that works in all of them.

In simple words: all Markdown shares one core. Extra features only work where the app supports them.

TL;DR

• CommonMark is the shared core of Markdown. Every modern app supports it.
• GitHub Flavored Markdown (GFM) adds tables, task lists, strikethrough, footnotes and automatic links to web addresses.
• Platform extensions are added by a single app: alerts, YAML frontmatter, Mermaid diagrams, maths, emoji codes.
• AI-native conventions are file names and structure that AI tools expect, like AGENTS.md. You will learn them in Chapter 3.
• To make a file portable, write the core first. Use extras only where every reader supports them, and know what each one turns into when it is not supported.

A Real-World Example

Think about English.

People in India, the UK and the US all speak English. Almost every sentence means the same thing everywhere. But a few words differ. In the UK, "pants" means underwear. In the US, it means trousers.

If you want everyone to understand you, you use the words that are the same everywhere. You use local words only when you know who is listening.

Markdown flavours work the same way. The core is the same everywhere. A few features are local.

What You Will Learn

In this lesson, you will learn:

1. The four layers of Markdown: CommonMark, GFM, platform extensions and AI-native conventions.
2. What GFM adds to CommonMark.
3. Which features only some apps support.
4. What each feature turns into where it is not supported.
5. How to write a file that looks the same everywhere.

Cheat Sheet

The Four Layers

Layer 1: CommonMark, the Core

Markdown was created in 2004. The first description was short and left many details open. So every app filled the gaps in its own way, and the same file rendered differently in each.

CommonMark fixed that in 2014. It is a detailed, tested description of exactly how Markdown works. Headings, paragraphs, lists, links, images, code, quotes, emphasis and escapes: everything you learned in Chapter 1 is CommonMark.

Today almost every Markdown app follows CommonMark for these basics. That makes the core the safest part of Markdown.

The core looks the same everywhere

# Refund policy

Refunds are allowed within **30 days**.

1. Open the order
2. Check the receipt

See the [shipping guide](docs/shipping.md) and run `npm test`.

> Ask a lead if you are not sure.

Press all three buttons. Nothing changes. Every line here is CommonMark.

Layer 2: GitHub Flavored Markdown

GitHub Flavored Markdown, or GFM, is CommonMark plus five extras. GitHub wrote them down as a formal spec, so other apps can copy them exactly. GitLab, VS Code and most docs tools support them.

The five GFM extras

| Plan | Price |
|---|---:|
| Basic | Free |

- [x] A task list item

~~Strikethrough~~ text

https://commonmark.org becomes a link.

A footnote reference.[^1]

[^1]: The footnote text, shown at the bottom.

Switch to CommonMark. Every one of the five extras turns back into plain text. GFM also filters risky HTML tags like <script>, which you saw in the last lesson.

Layer 3: Platform Extensions

Platform extensions are features added by one app or one kind of app. They are useful, but each one only works where that app supports it.

The Docs site button in this course shows a typical docs renderer: GFM plus alerts, hidden frontmatter and Mermaid diagrams.

Platform extensions on a docs site

---
title: Refund policy
owner: support-team
---

# Refund policy

> [!TIP]
> Most refunds are approved within one day.

```mermaid
flowchart LR
  A[Request] --> B[Check] --> C[Approve]
```

On the Docs site, the frontmatter is gone from the page, the tip is a green box, and the Mermaid code is drawn as a diagram. Now switch to CommonMark. The frontmatter turns into a divider line and a heading that reads "title: Refund policy owner: support-team". The tip is a plain quote. The diagram is just code.

Layer 4: AI-Native Conventions

The last layer is not about how Markdown renders at all. It is about where a file lives, what it is called, and how it is structured, so that AI tools find it and read it the right way.

• AGENTS.md at the root of a project is read by many coding agents at the start of every session.
• SKILL.md files start with frontmatter that has a name and a description.
• llms.txt is a Markdown index of a docs site, written for AI tools.

The Markdown inside these files is normal CommonMark and GFM. What makes them special is the convention around them. You will learn them in Chapter 3.

Maths and the Dollar Sign

Many docs sites draw maths written between dollar signs. That is useful for formulas, and a trap for prices.

Maths, and a price that turned into maths

The area of a circle is $\pi r^2$.

Express shipping costs $5 and $10.

Express shipping costs \$5 and \$10.

On the Docs site, the formula is drawn as maths. But the second line turned into maths too: everything between the two dollar signs became one formula. The third line escapes each dollar sign with a backslash, so it stays as text. Switch to GitHub (GFM): the GFM spec has no maths, so all three lines are plain text there.

Writing Portable Markdown

Know the Fallback

Every extra feature has a fallback: what it turns into when the app does not support it. Some fallbacks are fine. Some are bad.

Four Rules for Portable Files

1. Write the core first. Headings, paragraphs, lists, links and code work everywhere.
2. Use a safe form when one exists. <https://example.com> is a link in every flavour. A bare address is a link only in GFM.
3. Use extras only where you know the reader. A table in a GitHub README is fine. A table in a file that goes into a plain-text email is not.
4. Check the bad fallbacks. If a feature has a bad fallback, either keep it out of the file or add a plain version next to it.

The same README, made portable

# Order Support

> **Warning:** Refunds over ₹5,000 need a manager's approval.

Status page: <https://status.example.com>

## Release 2.4

- Done: Fix refund rounding
- To do: Add order search

Refunds take 5 days. Bank transfers can take longer.

Press all three buttons. This version reads the same in every flavour. The warning is a bold word in a quote. The link uses angle brackets. The task list uses words. The footnote became a normal sentence.

A Note About MDX

MDX is Markdown that can also contain small pieces of code called components. Many docs sites use it. This course is written in MDX.

MDX is stricter than Markdown. In MDX, a { starts a piece of code, and a < starts a component. So text like { "status": "shipped" } or List<T> in a normal sentence can break the whole page, not just one line. In MDX files, always put such text in backticks or code blocks.

Where This Matters

• README files that show on GitHub, on a package site like npm, and in an editor.
• Docs written once and published to a website and a PDF.
• Release notes pasted into chat apps and emails.
• Agent files read by AI tools that may not render Markdown at all, only read it as text.

Common mistakes

Quick Check

Exercises

What to Remember

• Markdown has four layers: CommonMark, GFM, platform extensions and AI-native conventions.
• CommonMark is the core that works everywhere: everything from Chapter 1.
• GFM adds tables, task lists, strikethrough, footnotes and automatic links.
• Alerts, frontmatter, Mermaid and maths are platform extensions. Each one works only where the app supports it.
• Every extra has a fallback. Know which ones are bad: tables, frontmatter and diagrams.
• For a portable file, write the core first and use safe forms like <https://…>.
• AI tools often read the raw text, so the raw text must make sense on its own.

Further Reading

• CommonMark: the spec and a live testing tool.
• GitHub Flavored Markdown spec: every GFM extra, with examples.
• Babelmark: one input rendered by many Markdown apps side by side.

Next: Docs as Code, where you lint a messy docs folder, add Mermaid diagrams and alerts, and write a README that answers the first five questions.