Written and maintained by CASRAI Editorial Board
Last updated
To add a footnote in Markdown, put a marker such as [^1] in the sentence and write the note on its own line as [^1]: Note text.. The processor numbers the notes automatically and prints them together, usually at the bottom of the page. Footnotes are an extension, not part of the original Markdown syntax, so the exact rules depend on the tool that turns your file into HTML, PDF or Word. This guide compares those rules and applies them to manuscripts and theses, where footnotes often carry citations and short asides.
The format
A footnote has two parts: a reference in the running text and a definition elsewhere in the file.
- Reference. A name prefixed with a caret, in square brackets:
[^1]. Python-Markdown describes the name as anything valid in an HTML id; other guides restrict it further (see the flavour section below). - Definition. Per the Python-Markdown documentation, a definition “must start with the corresponding footnote reference followed by a colon and at least one space”. The note text may start on the same line or on the next one.
- Extra paragraphs. Indent each further paragraph one level, which is four spaces or one tab. Python-Markdown allows definitions to hold paragraphs, code blocks and blockquotes.
- Placement. GitHub Docs states that the position of a footnote definition in your Markdown does not influence where it is rendered; notes appear at the bottom.
Examples
The sources below are fictitious and are used only to show the syntax.
A single-line note
The pilot sample was recruited in two waves.[^1]
[^1]: Example note: wave two added 12 participants after the first interim check.A word as the label
Interview transcripts were coded twice.[^coding]
[^coding]: Example note: two coders worked independently and reconciled differences.The label is for you, not the reader. The processor replaces the label with a generated number in the output, so the reader sees a number rather than the word.
A multi-paragraph note
The dataset was filtered before analysis.[^filter]
[^filter]: Example note: records with missing outcome values were removed.
The second paragraph is indented four spaces so it stays inside the note.A line break inside a note
GitHub Docs says to end a line with two spaces to force a line break inside a footnote.
Citing sources in a footnote
In a manuscript or thesis, a footnote is a convenient place for a citation or a short aside that would interrupt the argument. Markdown does not format the citation for you: the note is plain text, so you type the reference in whatever style your journal or institution requires. A fictitious example:
Earlier work reported the same trend.[^prior]
[^prior]: Example only: Author, A. (2020). An invented article title. Journal of Examples, 1(1), 1-10.If your citations come from a reference manager, see citations in Quarto, R Markdown and Pandoc for generating citations instead of typing them. For how footnote-style citations are formatted in one style, see MLA footnotes. Journals set their own manuscript requirements, so check manuscript format for journal submission before relying on notes at all.
Numbering is automatic. Python-Markdown orders notes by definition order by default (USE_DEFINITION_ORDER is True; setting it to False is documented as experimental). Because the printed number can change when you add, move or reorder notes, a hand-written cross-reference such as “see note 3” can become wrong after editing. Refer to a section or table instead. If you are moving a manuscript between Markdown and Word, see how to remove footnotes in Word.
Pandoc includes footnote syntax in Pandoc Markdown and has a --reference-location option that sets whether notes are placed at the end of the block, the section or the document (document is the default). End-of-section notes can suit a long thesis chapter.
Common errors
- Reference and definition do not match. Python-Markdown requires the definition label to match the reference exactly, including capitalization and white space.
[^Note]and[^note]are different notes. - Missing colon or space. A definition needs the colon and at least one space after it.
- Second paragraph not indented. Both Python-Markdown and Markdown Guide say to indent further paragraphs by four spaces (Python-Markdown also accepts one tab); an unindented paragraph is not part of the note.
- Spaces in the label. Markdown Guide says identifiers cannot contain spaces or tabs, while Python-Markdown allows them. Plain letters or digits are the safest choice across tools.
- Definition inside a list, block quote or table. Markdown Guide says definitions can go anywhere except inside those structures. Put them at the top level of the file.
- Expecting the label to print. Only the generated number is displayed, as noted above.
- Using footnotes in a GitHub wiki. GitHub Docs states that footnotes are not supported in wikis.
Which Markdown flavours support footnotes
There is no single specification, so what works depends on the processor. The documented differences:
| Tool | What its documentation says |
|---|---|
| Python-Markdown (Footnotes extension) | Labels may contain spaces. Notes render at a place marker (default ///Footnotes Go Here///) or, if there is none, at the end of the output. Options include PLACE_MARKER, BACKLINK_TEXT and SEPARATOR. |
| GitHub (basic writing syntax) | Syntax is [^1] plus [^1]: text. Notes render at the bottom regardless of where the definition sits. Not supported in wikis. |
| Pandoc | Pandoc Markdown includes footnote syntax; --reference-location controls where notes land. |
| Markdown Guide (extended syntax) | Describes the common syntax. Identifiers cannot contain spaces or tabs, and it advises checking each processor’s own documentation for support. |
Because the label rule differs between sources, the safest portable choice is a short label with no spaces, defined at the top level of the file.
FAQ
How do I add a footnote in Markdown?
Write [^1] where the note belongs and add [^1]: Your note. on its own line elsewhere in the file. The processor numbers and places the notes for you.
Can I use words as footnote labels?
Yes, but avoid spaces: Markdown Guide forbids them even though Python-Markdown permits them. The label is never shown; the reader sees a number.
Do markdown footnotes work on GitHub?
Yes. GitHub’s basic writing syntax includes footnotes and renders them at the bottom. GitHub Docs states they are not supported in wikis.
Where do the notes appear?
That depends on the tool. GitHub renders them at the bottom; Python-Markdown uses a place marker or the end of the output; Pandoc lets you choose block, section or document.
Sources
- Python-Markdown, Footnotes extension: python-markdown.github.io/extensions/footnotes (checked 2026-10-29).
- GitHub Docs, Basic writing and formatting syntax: docs.github.com (checked 2026-10-29).
- Markdown Guide, Extended syntax: markdownguide.org/extended-syntax (checked 2026-10-29).
- Pandoc User’s Guide: pandoc.org/MANUAL.html (checked 2026-10-29).
