Footnotes in Markdown are an excellent way to add side comments or notes without interrupting the primary text flow. In this tutorial, we’ll go over how to use footnotes in your Markdown files effectively.

Syntax of Markdown Footnotes

Footnotes in Markdown are created using a two-part system: the footnote reference and the footnote definition.

Footnote Reference

Usually placed at the point where you want to insert the footnote in your text, the syntax is [^1] or [^footnote1]. The ^ character followed by an identifier inside brackets [] will create the footnote reference.

Let’s look at an example:

This is some text with a footnote[^1].

Footnote Definition

This is where you provide the footnote information. You would typically place this at the end of your Markdown document. The syntax is [^1]: or [^footnote1]: followed by your footnote text.

Here’s how you would define the footnote for the above example:

[^1]: This is the footnote text.

Expanded Example

Let’s take a look at a more extensive example that includes several footnotes:

This is some text with footnotes[^1][^2].

[^1]: This is footnote 1.
[^2]: This is footnote 2.

When rendered, this Markdown will create the footnotes at the bottom of your document, each linked to their reference in the text.

Note that the identifiers for the footnotes can be numerical or textual, as long as they match between the footnote reference and its definition.

Using Markdown Footnotes Across Different Platforms

Markdown flavor may differ across various platforms and tools, and support for footnotes specifically is uneven. GitHub added native footnote rendering in September 2021, so [^1] now renders as a real, clickable footnote in issues, pull requests, and repository files there — this wasn’t always true, and if you’ve seen older advice claiming GitHub doesn’t support footnotes, that’s why. Footnotes also render natively on GitLab, in Obsidian, and on Jekyll sites using kramdown (the processor this blog itself runs on). Other platforms — Notion, Slack, Jira, and Confluence among them — still don’t support footnote syntax at all, and some static site generators like MkDocs need an extension explicitly enabled before footnotes will render. See our full platform-by-platform footnote breakdown for the current state of each.

Always make sure what type of Markdown your platform uses before incorporating footnotes.

Rendering Markdown Footnotes

Markdown files are often manually converted to HTML for displaying on websites. However, if these files are used as part of a software project, such as a React or Angular App, or any back-end system like Ruby on Rails or Node.js Express App, you may need to programmatically convert these markdown files to HTML at runtime.

To know more about rendering markdown in various platforms, check out these articles on rendering markdown in React, Angular, and Ruby on Rails.

Tools and Further Reading

If you’ve edited a document enough times that your footnote numbering has drifted out of order, our Footnote Organizer will renumber everything sequentially by reference order and collect the definitions at the end for you, rather than you doing it by hand. And for the full picture of which platforms actually render footnotes versus which just show you the raw syntax, see Markdown Footnotes Across Platforms.

Conclusion

Footnotes are important for improving the readability of your Markdown files, allowing you to provide additional comments or asides without interrupting the progression of your main text. By being aware of how to correctly implement footnotes, you can avoid common pitfalls and effectively use this feature in your Markdown files.

Remember that the availability of footnotes and their specific implementation can vary between different flavors of Markdown. Always ensure you’re using the correct format for your specific platform or use case.