---
title: "Markdown footnotes: syntax and why they don't render"
slug: markdown-footnotes
excerpt: "How to write [^1] footnotes, why a note shows up as raw bracket text, how to fix it, and plain fallbacks for viewers without footnotes."
quickAnswer: "A Markdown footnote has two parts. You put a marker like [^1] in the sentence, then a line like [^1]: The note text. somewhere else in the file. Footnotes are not part of the CommonMark spec. They come from extensions, and the pandoc manual documents the syntax. A viewer without the extension may keep [^1] as plain text, and a one-word note can even turn into an odd link. When footnotes do not render, check four things: viewer support, a matching definition for every marker, no spaces in the label, and a definition that sits outside lists, quotes, tables and code blocks. If your viewer has no footnote support, close the file with a short Notes section instead."
keyTakeaways:
  - "Footnotes are an extension. Plain CommonMark has no footnote rule, so [^1] stays as text unless a matching definition turns it into a link."
  - "Pandoc's syntax pairs a marker like [^1] with a definition line like [^1]: Note text, and the definition may sit almost anywhere in the file."
  - "Pandoc labels may not contain spaces, tabs, newlines, ^, [ or ]."
  - Pandoc does not allow a definition inside a list, block quote or table, and text in a code fence is never parsed.
  - "When a viewer has no footnotes, a plain Notes section or a short parenthetical needs no extension at all."
publishedDate: 2026-10-20
dateModified: 2026-10-20
author: Bobby Huang
cluster: B
role: post
status: published
faq:
  - q: What makes a footnote show as [^1] on the rendered page?
    a: "One common cause is a viewer with no footnote extension. Such a viewer may follow plain CommonMark and leave the brackets as text. If the viewer does support footnotes, look for a missing or misspelled definition, a space in the label, or a definition placed inside a list, quote, table or code block."
  - q: Can a footnote have more than one paragraph?
    a: "In pandoc's syntax, yes. Indent each extra paragraph under the definition line, the way you would indent more text under a list item. A paragraph that is not indented ends the note once a blank line comes before it. Pandoc's inline notes, written as ^[text], cannot hold more than one paragraph."
  - q: Do footnotes have to go last in the file?
    a: "Not in pandoc. A definition may appear anywhere outside lists, block quotes and tables, with a blank line before and after it. Pandoc numbers the notes in order in its output. Grouping them at the bottom still keeps the raw file tidy."
related:
  - markdown-syntax-guide
  - markdown-cheat-sheet
  - rendered-vs-raw-agent-markdown
---

Footnotes let you park a source or an aside at the bottom of a page and leave a small number in the sentence. Agents may use them for citations in research notes. Open that file in another app, though, and the number may turn into raw `[^1]` text.

That happens because footnotes sit outside core Markdown. This post covers the syntax pandoc documents, a numbered fix pass for notes that don't render, and fallbacks for viewers that lack the feature. Core elements live in the [syntax guide](markdown-syntax-guide.md).

## Footnotes are not in CommonMark

No footnote rule exists in the CommonMark spec. Its intro mentions footnotes only as something some implementations added on top of the original Markdown. Support comes from extensions, and the pandoc manual is a good written source for the syntax. Pandoc treats footnotes as an extension you can switch on or off.

That matters, because a CommonMark parser still reads the brackets. It sees them as a possible link.

- **A marker with no matching definition stays as text.** `[^1]` is a valid link label, since a label may hold `^`; it just can't hold an unescaped `[` or `]`. Without a matching definition, it doesn't form a link, and the brackets print as written.
- **A multi-word note becomes a plain paragraph.** A line like `[^1]: Here is the note.` looks like a link reference definition, but the words after `Here` are not a title in quotes or parentheses, so the line breaks the rule for a definition. So the whole line prints as an ordinary paragraph.
- **A one-word note can become a link.** A line like `[^1]: Done.` is a valid link reference definition. Its label is `^1` and its destination is `Done.`. The marker `[^1]` in your sentence then becomes a link whose text is ^1 and whose target is `Done.`.

One file can therefore show a neat note in one app, raw brackets in another, and a strange link in a third.

## Footnote syntax, the pandoc way

A footnote has two halves: the marker in the text and the definition that holds the note.

```markdown
Jane Doe signed off on the budget.[^1] The vendor list came later.[^vendors]

[^1]: Approved in the March planning meeting.

[^vendors]: Doe Holdings sent the list in April.

    It covered three suppliers. This paragraph is indented,
    so it still belongs to the note.

This paragraph is not indented, so it is not part of the note.
```

A few rules from the pandoc manual:

- **The marker** is a caret and a label inside brackets, placed right after the word it annotates.
- **The definition** repeats the marker, adds a colon, then the note text.
- **Extra paragraphs** go under the definition, indented. You can indent the whole paragraph or just its first line, the same way list items hold more than one paragraph. The note ends at the first unindented paragraph that follows a blank line.
- **Labels only link the pair.** Pandoc numbers the notes in order in its output, so `[^vendors]` still shows as a number.
- **Inline notes** skip the label. Pandoc's `inline_notes` extension lets you write `^[The note text.]` right in the sentence. An inline note can't hold more than one paragraph. You can mix both styles in one file.

### Where definitions may go

Pandoc doesn't require notes to sit last in the file. A definition can appear anywhere except inside another block element, such as a list, a block quote or a table. Leave an empty line above and below each one, including between two definitions. Many writers still keep every note at the bottom so the raw file stays tidy.

### Label rules

Pandoc labels may not contain spaces, tabs, newlines, or the characters `^`, `[` or `]`. Short labels like `1`, `2` or `vendors` are the safest choice. A label like `[^vendor list]` breaks the rule.

## Fix a footnote that won't render

Go step by step.

1. **Check that the viewer supports footnotes.** Make a test file with one marker and one definition and open it. If you see raw `[^1]` text, the viewer likely has no footnote extension, and nothing in your file will fix that. Skip to the fallbacks below.
2. **Match every marker to a definition.** Each `[^label]` in the text needs a `[^label]:` line with the same label. A typo like `[^vendor]` against `[^vendors]` leaves the marker as plain text in many viewers.
3. **Take spaces out of labels.** Swap `[^vendor list]` for `[^vendors]` in both the marker and the definition.
4. **Move definitions out of other blocks.** A definition indented under a list item or placed inside a block quote or table breaks pandoc's placement rule. Inside a code fence the line is just literal text, because fence content is never parsed as Markdown. See [Markdown code blocks](markdown-code-blocks.md) for where fences start and end.
5. **Add blank lines.** Give each definition an empty line above and below.
6. **Check the indent on long notes.** If the second paragraph of a note shows up in the main text, indent it under the definition line.

Then open the rendered file again. A note that still fails after all six steps points back to step 1.

## Fallbacks when the viewer has no footnotes

If your readers use a viewer without footnote support, write notes that need no extension.

**A Notes section.** Put a plain number in brackets in the sentence, and end the file with a numbered list.

```markdown
Jane Doe signed off on the budget [1]. The vendor list came later [2].

## Notes

1. Approved in the March planning meeting.
2. Doe Holdings sent the list in April.
```

Under CommonMark, `[1]` with no matching definition stays as plain text, so it reads as [1] both in the source text and on the page. Don't write the notes as `[1]: text` lines, though. A one-word note in that form can turn into a link, as shown above.

**A parenthetical.** For a short aside, put it in the sentence: "The vendor list came later (Doe Holdings sent it in April)." There is no syntax to break.

Some writers use a raw HTML `sup` tag for a raised number. Viewers differ in what they do with HTML, so read the post on [HTML inside Markdown](raw-html-in-markdown.md) before you count on it.

## Tips for agent-written files

Agents may add footnotes for sources on their own. A few habits keep those notes readable.

1. **Say which style you want.** If your team's viewers lack footnotes, tell the agent in its instruction file to use a Notes section with plain numbers. Our [agent rule-writing guide](write-markdown-docs-your-ai-agent-can-follow.md) has more on phrasing.
2. **Ask for simple labels.** Numbers or one short word, no spaces.
3. **Ask for definitions at the bottom,** each with a blank line around it, never inside a list.
4. **Check pairs with one command.** Run `grep -oE '\[\^[^]]+\]' notes.md | sort | uniq -c`. Each label should appear at least twice, once as a marker and once in its definition. A count of 1 points to a missing half.
5. **Read the raw file once.** The post on [rendered and raw views](rendered-vs-raw-agent-markdown.md) explains why some problems only show in one view. The [cheat sheet](markdown-cheat-sheet.md) puts every other element on one page.

## Where Sashmark fits

Sashmark is a planned desktop app for people who read and edit the Markdown files their agents write. It is in development and has not been released. The app itself has no AI features. For v1, the plan lists live rendering for headings, lists, tables, check-box lists, block quotes, code blocks, links and images stored on your computer; footnotes are not on that list. To see what is planned and where each part stands, read the [planned features](/features), the [roadmap](/roadmap) and the [help pages](/help).

Follow the project at [sashmark.com](https://www.sashmark.com/).