Markdown Extensions: GFM, MDX, and Beyond

Beyond Standard Markdown

Original Markdown, defined by John Gruber in 2004, covers basics: headings, emphasis, links, images, and lists. But modern writing demands more — tables, task lists, math equations, interactive components.

That is where extensions come in. They extend the base syntax while preserving Markdown's core philosophy: readable in raw form, powerful when rendered.

GitHub Flavored Markdown (GFM)

GFM is the most widely used Markdown extension. GitHub developed it to address gaps in the original spec, and most modern parsers support it by default.

Tables

GFM adds table syntax that renders HTML <table> elements:

| Feature    | GFM | Standard |
|------------|:---:|:--------:|
| Tables     | Yes | No       |
| Task lists | Yes | No       |
| Strikethrough | Yes | No    |

Alignment colons work exactly as in standard table syntax: :--- for left, :---: for center, ---: for right.

Task Lists

Checkboxes turn lists into interactive to-do items on GitHub:

- [x] Set up project structure
- [x] Write documentation
- [ ] Deploy to production
- [ ] Monitor performance

On GitHub, these render as clickable checkboxes. In static sites, they typically render as checked or unchecked icons.

Strikethrough

Use double tildes for deleted text:

This is ~~outdated~~ current information.

Renders as: This is outdated current information.

Autolinks

GFM automatically converts URLs into clickable links without angle brackets:

Visit https://github.com for more details.

Standard Markdown requires <https://github.com> for autolinking. GFM removes that necessity.

Disallowed Raw HTML

GFM sanitizes certain HTML tags for security. Tags like <script>, <title>, and <style> are stripped from output. This prevents XSS attacks in user-generated content.

MDX: JSX in Markdown

MDX lets you write JSX components directly inside Markdown. It bridges the gap between prose content and interactive UI elements.

Basic Usage

import Chart from './components/Chart'

# Quarterly Report

Revenue grew 23% year-over-year.

<Chart data={quarterlyData} />

Why MDX Matters

• Interactive content: Embed charts, calculators, and dynamic widgets inside documentation
• Component reuse: Use your React/Vue component library within Markdown files
• Type safety: MDX files work with TypeScript for props and imports
• Ecosystem: Works with Next.js, Nuxt, Astro, and most modern frameworks

MDX vs Standard Markdown

Use MDX when your docs need interactive elements. Stick with standard Markdown for simple articles and READMEs.

Math and KaTeX

Math rendering turns LaTeX notation into beautifully typeset equations. KaTeX and MathJax are the two leading renderers.

Inline Math

Wrap expressions in single dollar signs:

The formula $E = mc^2$ changed physics forever.

Block Math

Use double dollar signs for display equations:

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Common Math Examples

Math support is not part of core Markdown. It requires a plugin — check your platform's documentation for setup.

Footnotes

Footnotes let you add references without cluttering the main text:

This claim needs a source.[^1]

DITA and AsciiDoc offer alternatives.[^note]

[^1]: Smith, J. "Markdown Extensions," 2025.
[^note]: See the DITA OASIS standard for comparison.

Footnotes render as superscript numbers in the text body and as a numbered list at the bottom of the document.

Frontmatter

Frontmatter adds metadata to Markdown files using YAML between triple-dashed lines:

---
title: "Getting Started with Markdown"
date: 2026-05-27
author: "Jane Doe"
tags:
  - markdown
  - documentation
draft: false
---

# Getting Started with Markdown

Content starts here...

Static site generators like Nuxt Content, Hugo, and Jekyll read frontmatter to populate page titles, dates, categories, and templates. It is the standard way to separate content from configuration.

Common Frontmatter Fields

Diagram Support

Some platforms support Mermaid diagrams inside fenced code blocks:

```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
    C --> D

Mermaid renders flowcharts, sequence diagrams, class diagrams, Gantt charts, and more — all from text-based definitions. GitHub supports Mermaid natively in READMEs and issues.

## Other Notable Extensions

- **Admonitions:** Callout blocks for warnings, tips, and notes (supported by Docusaurus, Material for MkDocs)
- **Attributes:** Add CSS classes and IDs to elements (`{: .highlight}`)
- **Definition lists:** Term/definition pairs (PHP Markdown Extra, kramdown)
- **Abbreviations:** Hover-text definitions (`*[HTML]: HyperText Markup Language`)
- **Subscript and superscript:** `H~2~O` for H₂O, `X^2^` for X² (some parsers)

## Compatibility Checklist

Before adopting an extension, ask:

1. **Do your target platforms support it?** GFM works almost everywhere. MDX and Mermaid require build tools.
2. **Will the raw text remain readable?** If the source looks like code, you lose Markdown's core advantage.
3. **Is the extension actively maintained?** Avoid abandoned plugins that may break with updates.
4. **Does it degrade gracefully?** If a parser ignores the extension, the content should still make sense.

## Related Guides

- [Markdown Syntax Guide](/guides/markdown-syntax-guide)
- [Markdown Best Practices](/guides/markdown-best-practices)
- [CSS Color Functions](/guides/css-color-functions)

## Try It Yourself

Experiment with these extensions using our free [Markdown to HTML Converter](/tools/markdown-to-html). Write GFM tables, code blocks, and more — then see the rendered HTML output in real time.