Markdown footnotes are useful, but they are also one of the easiest places to over-assume portability.
If you only remember one thing, remember this:
footnotes are not part of core CommonMark.
That means footnote behavior depends much more on your renderer and export pipeline than many authors realize.
The Core Distinction: CommonMark vs Extensions
CommonMark defines the baseline Markdown syntax. Footnotes are not included in that core baseline.
So when someone says “Markdown supports footnotes,” the more accurate version is:
- some Markdown environments support footnotes
- many support the familiar
[^1]style - but support is not universal
This matters because a document can look correct in one renderer and lose footnote behavior in another.
Basic Footnote Syntax
The most common pattern is:
Here is a footnote reference.[^1]
[^1]: The footnote text.
You can also use named labels:
Export quality matters.[^export]
[^export]: Review one real export before sharing.
Named labels are often easier to maintain in long documents because they remain readable after edits.
Footnotes in GFM-Style Workflows
GitHub-flavored Markdown environments commonly support the familiar footnote reference and definition syntax.
That makes footnotes practical for:
- documentation notes
- source citations
- side comments that would clutter the main paragraph
But this is still an extension-level feature. Do not confuse “works on GitHub or a GFM renderer” with “portable everywhere.”
If the document also depends on section links or exported references, coordinate footnotes with clear heading structure instead of using notes as a place to hide navigation-critical context.
Pandoc Goes Further Than Basic Footnotes
Pandoc supports the common footnote style, but it also supports features that many generic Markdown guides never mention.
Inline footnotes
Pandoc supports inline footnotes:
Export once before sending the file.^[This avoids trusting preview alone.]
That is convenient in some writing workflows, but it is not a universal Markdown feature.
Multi-paragraph footnotes
Pandoc also supports more complex footnote content, including multiple paragraphs, when the indentation is correct.
That can be useful in scholarly or documentation-heavy writing, but it also raises the chance of renderer differences and export surprises.
Where Footnote Definitions Can Break
This is the part many basic guides omit.
In Pandoc, footnote definitions cannot appear inside certain block structures such as:
- lists
- block quotes
- tables
That means a pattern like this is risky:
- Main point[^1]
[^1]: Footnote text
Safer approach:
- Main point[^1]
[^1]: Footnote text
Keep footnote definitions at the document flow level unless you know the exact renderer rules you are targeting.
If your notes sit inside list-heavy or quote-heavy sections, review Markdown List Guide and Markdown Quote Guide before assuming the structure will stay stable after export.
Footnotes and Word/PDF Export
This is where expectations often drift.
A renderer may visually support footnotes in preview, but exported output depends on the actual conversion pipeline. In some workflows, footnotes may become:
- true footnotes
- linked notes at the end of the document
- plain superscripted references with note blocks
Do not promise yourself a specific export behavior until you test the actual DOCX or PDF output.
When Footnotes Help, and When They Hurt
Footnotes are useful when:
- the main paragraph should stay readable
- the note is secondary, not essential to understanding the sentence
- you are adding citations, caveats, or references
Footnotes become a liability when:
- the note contains critical instructions the reader must not miss
- the document relies on a renderer that may flatten or restyle footnotes
- the writing already has too many structural dependencies
If a note is essential, it may belong in the main text or in a clearly labeled callout instead.
Practical md2word Advice
This section reflects the current md2word content and rendering setup rather than generic Markdown folklore.
Unlike images, Mermaid, or display-math normalization, the current repo does not add a special footnote preprocessing layer. The safest behavior still comes from plain reference-style footnotes plus renderer support.
1. Basic [^label] footnotes are the safest starting point
This is the most recognizable and widely supported footnote pattern in modern Markdown ecosystems.
2. Prefer named labels in long technical documents
[^export-warning] is easier to maintain than [^7] after heavy editing.
3. Keep definitions outside lists and other nested blocks
This is one of the easiest ways to avoid cross-renderer surprises.
4. Do not assume preview equals final export
If the exact footnote behavior matters in Word or PDF, test one real export.
5. Avoid using footnotes for essential instructions
If the reader must see it, keep it in the main flow.
Common Mistakes
1. Assuming footnotes are standard Markdown
They are not.
2. Hiding critical information in a footnote
That is a readability problem before it is a formatting problem.
3. Putting footnote definitions inside lists or other nested blocks
That can break parsing or portability.
4. Using inline footnotes without checking renderer support
That is a Pandoc-oriented feature, not a universal guarantee.
5. Assuming exported DOCX/PDF will preserve exactly the same footnote semantics as preview
That must be tested, not assumed.
FAQ
Are footnotes part of standard Markdown?
No. They are not part of core CommonMark. Treat them as renderer- or extension-dependent behavior.
Should I use numeric labels or named labels?
Named labels are often easier to maintain in long documents. Numeric labels are fine for short notes.
Are inline footnotes safe to use everywhere?
No. Inline footnotes are mainly a Pandoc-style feature and should not be treated as universal Markdown.
Can I place footnote definitions inside a list item?
That is risky. In Pandoc-oriented workflows, footnote definitions should not be placed inside lists, block quotes, or tables.
What is the safest footnote strategy for export?
Use standard reference-style footnotes, keep definitions at the document flow level, and test one real export if the note behavior matters.
Further Reading
Changelog
- 2026-03-18: Initial high-value release with verified guidance on CommonMark limits, GFM/Pandoc differences, footnote definition placement, and export-oriented cautions.
- 2026-03-19: Added stronger guidance on coordinating footnotes with heading structure and on md2word's lack of a special footnote preprocessing layer.
Next steps: Explore Markdown Cheat Sheet, Markdown Export Tips, Markdown List Guide, Markdown Quote Guide, and Markdown Hyperlink.