MultiMarkdown: Syntax and How It Differs from CommonMark

MultiMarkdown (often searched as multi markdown) is Fletcher Penney's extended Markdown dialect that adds tables, footnotes, citations, metadata, math, definition lists, and file transclusion to the original syntax. This guide gives you one worked example per feature, a comparison table against CommonMark and GFM, and an honest note on the project's status in 2026.

What Is MultiMarkdown and Is It Deprecated?

MultiMarkdown (MMD) started in 2007 as a Perl script that bolted academic features onto John Gruber's Markdown. Version 6 was a full rewrite in C, and its command line tool converts a text file to HTML, LaTeX, OpenDocument, EPUB 3, and OPML. It predates CommonMark by seven years, so several ideas that feel standard today, footnotes above all, came from here. The short MultiMarkdown vs Markdown answer: same core, plus a dozen extensions aimed at long and academic documents.

The confusing part is the GitHub repo. The MultiMarkdown-6 repository now carries the GitHub description "This project is now deprecated. Please use MultiMarkdown-7 instead!" That doesn't mean MMD is dead. It means development moved to MultiMarkdown-7, which sits at 7.0.0-beta.2 as of July 2026 and, per its README, supports everything v6 did except OpenDocument export.

Version 6 still installs and still works. The Homebrew formula brew install multimarkdown gives you 6.8.0, and the v6 syntax is what Scrivener, Marked 2, and MultiMarkdown Composer speak. So when you write MMD today, you're writing the v6 dialect, and v7 reads it unchanged.

MultiMarkdown vs CommonMark vs GFM

This is the table none of the official pages give you. "Later adopted" means the same or a near-identical syntax shows up in other flavours.

Feature	MultiMarkdown 6	CommonMark 0.31	GFM (GitHub)	Later adopted elsewhere
Pipe tables	Yes, with captions and colspan	No	Yes, no captions or colspan	PHP Markdown Extra, Pandoc
Footnotes [^id]	Yes	No	Yes (same syntax)	Pandoc, Obsidian, VS Code plugins
Definition lists	Yes	No	No	PHP Markdown Extra, Pandoc
Metadata block	Yes (key: value at line 1)	No	No	YAML front matter took over
Math $...$	Yes	No	Yes (since 2022)	Obsidian, Jupyter, Pandoc
Citations [#key]	Yes	No	No	Pandoc uses [@key]
File transclusion	Yes	No	No	Obsidian embeds ![[file]]
CriticMarkup	Yes	No	No	Editors like iA Writer
Cross-references [Heading][]	Yes	No	Auto heading anchors only	Pandoc
Link and image attributes	Yes (width=)	No	No	Pandoc, kramdown
Smart typography	Yes	No	No	Pandoc smart, Typora
Superscript ^2^ and subscript ~2~	Yes	No	No (single ~ is strikethrough)	Pandoc

If you only need the basics, our Markdown cheat sheet covers the shared core. Everything below is what MMD adds on top.

MultiMarkdown Syntax: One Example per Extension

Each snippet is the v6 syntax as documented in the MultiMarkdown User's Guide. The behaviours described are the ones the guide documents for the 6.x binary.

Metadata

Metadata must start on line 1 with no blank line before it. Each line is key: value, and the first blank line ends the block. MMD's guide lists over two dozen standard keys, including title, author, date, css, latex leader, and transclude base.

Title: Quarterly Report
Author: Dana Ortiz
Date: 2026-09-11
CSS: report.css

The first blank line above ends the metadata.

The HTML output puts title in the <title> tag and the rest into <meta> elements. Add a blank line at the top of the file and the whole block turns into a plain paragraph.

Tables with Captions and Colspan

MMD tables look like GFM tables, with two additions. A line of the form [Caption] directly before or after the table becomes a <caption>. Two consecutive pipes at the end of a cell make it span two columns.

| Quarter | Revenue | Costs |
|:--------|--------:|------:|
| Q1      | 120     | 80    |
| Q2 total spans both ||
[Quarterly figures]

The rules are strict: every row needs at least one pipe, the separator line may only contain |, -, =, :, ., +, and spaces, and a cell can't wrap onto a second line. Our Markdown table guide covers the GFM subset that works everywhere.

Footnotes

This is MMD's most successful export. The syntax is identical in GFM, Pandoc, and Obsidian.

Footnotes were in MMD from the start.[^first]

[^first]: GitHub adopted the same syntax years later.

GitHub documents the same form in its basic formatting syntax, with the caveat that wikis don't render them. Our Markdown footnotes post tracks per-platform support.

Definition Lists

A term on its own line, followed by one or more definitions that start with a colon and a tab or spaces.

CommonMark
:   A strict specification with 652 spec examples.
:   Version 0.31.2 is current.

MultiMarkdown
:   An extended dialect, not a specification.

MMD renders this as <dl>, <dt>, and <dd>. GitHub shows it as a paragraph with odd colons.

Citations and BibTeX

Citations use the same reference-link shape as footnotes, with # instead of ^. The optional first bracket holds a locator such as a page number.

The parser was rewritten in C.[p. 3][#penney2017]

[#penney2017]: Fletcher Penney. *MultiMarkdown 6 Users Guide*. 2017.

With the bibtex metadata key pointing at a .bib file, MMD pulls entries from it instead. LaTeX output turns each citation into \cite.

Math

MMD accepts \(...\) and \[...\] as well as $...$ and $$...$$. For the dollar form there must be no space inside the delimiters and there must be space outside them. In HTML output the math is passed through for MathJax; in LaTeX output it's native.

Inline: \(E = mc^2\) or $E = mc^2$

Display:
\[ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} \]

Which delimiters a given renderer accepts is the whole subject of our Markdown equation guide. Short version: $ works in far more places than \(.

File Transclusion

Transclusion is MMD's answer to the recurring question "how do I combine several Markdown files into one?" Wrap a filename in double curly braces and MMD inserts that file at that point, recursively.

Title: Book
Transclude Base: chapters/

{{01-intro.md}}
{{02-setup.md}}
{{figures/*}}

The transclude base metadata key sets the folder to search. A wildcard extension like {{file.*}} picks file.tex for LaTeX output and file.html for HTML. Run multimarkdown -t mmd book.md and you get one flat Markdown file with every transclusion resolved, which is the export path other tools can read.

CriticMarkup

MMD understands the five CriticMarkup marks for tracked changes: {++insert++}, {--delete--}, {~~old~>new~~}, {==highlight==}, and {>>comment<<}. Command line flags let you accept all changes, reject all changes, or render the marks visibly.

The parser is {--slow--}{++fast++} and {~~mostly~>fully~~} tested.{>>Check this.<<}

Cross-References, Attributes, and Typography

Any heading is a link target: [Setup][] links to a heading called Setup, and ## Setup [setup-id] gives it a custom ID. Reference-style links and images accept trailing attributes such as width=300px class=hero. Smart typography turns straight quotes into curly ones, -- into an en dash, and ... into an ellipsis unless you disable it with --nosmart.

Superscript is x^2^ and subscript is H~2~O. Watch that second one: GFM treats a single tilde pair as strikethrough, so the same text renders differently on GitHub.

Try MultiMarkdown Syntax in a GFM Renderer

The editor below is a CommonMark-plus-GFM renderer, the kind you meet on GitHub and in most web apps. Paste an MMD feature in and you'll see which extensions survived. In our testing, the table and math render, single-tilde subscript becomes strikethrough, and definition lists and CriticMarkup come out as literal text. Footnotes and the {{TOC}} macro, which we left out of the sample, print literally here as well.

Compare that against multimarkdown -t html file.md, or paste the same text into our Markdown to HTML converter to see the GFM output as raw markup.

Which Tools Still Read MultiMarkdown?

The command line binary is the reference. On macOS, brew install multimarkdown installs 6.8.0; Linux and Windows users build v6 or v7 from source with CMake. Marked 2 and MultiMarkdown Composer ship the MMD engine, and Scrivener uses it for its MultiMarkdown compile formats. Emacs markdown-mode runs whatever binary you set as markdown-command, so pointing it at multimarkdown works.

Pandoc is the pragmatic alternative. Its markdown_mmd input format reads MMD tables, footnotes, definition lists, metadata, and link attributes, though not transclusion or CriticMarkup. We prefer Pandoc for new projects because it's actively released and its citation syntax has far wider library support. Keep the MMD binary around for legacy Scrivener projects and for transclusion.

One limitation to plan around: no browser-based renderer we know of implements the full MMD feature set, so a README written in MMD will show literal citations and definition lists on GitHub.

Common MultiMarkdown Mistakes

A blank line before the metadata. Metadata must begin on line 1. A leading blank line, a comment, or a BOM turns the whole block into a paragraph and drops the title from the HTML output.

Expecting ~2~ to mean subscript on GitHub. GFM only knows single tildes as strikethrough. If the file targets both, write subscripts as <sub>2</sub>, which every HTML-passing renderer accepts.

Using {{file.md}} outside MMD. Transclusion happens inside the MultiMarkdown binary, not in the file format. Other renderers print the braces. Export with -t mmd first, then hand the flattened file to whatever tool comes next.

MultiMarkdown FAQ

MultiMarkdown gave Markdown its footnotes, tables, and metadata years before other flavours caught up, and the v6 dialect still runs on every platform through Homebrew, Scrivener, or a source build. Treat multi markdown syntax as a superset: the shared core renders everywhere, the extensions render in MMD-aware tools. Paste your file into the editor to see exactly where that line falls.