Footnote syntax — a reference marker like [^1] in the body text, paired with a definition [^1]: The actual note. elsewhere in the document — looks the same everywhere you write it. Whether it renders as anything at all is a different question entirely, and the answer splits sharply by platform: some render real, clickable, jump-linked footnotes with zero configuration; others don’t understand the syntax at all and will show you the literal brackets and carets. This is a reference for which is which, checked against real output rather than assumed from a spec.

If you haven’t used footnote syntax before, our footnotes in Markdown guide covers the basic syntax first. If you’re doing heavier academic-style citation work, see our citations and references guide. This post is specifically about the one thing those guides don’t fully settle: does your renderer actually turn [^1] into a footnote, or not.

Native support, no configuration needed

GitHub added real footnote rendering in September 2021 — this is worth calling out explicitly, because plenty of older Markdown content (including, until this post, our own footnotes guide) still says GitHub doesn’t support them, which was true before that date and isn’t anymore. Today, [^1] in an issue, pull request, wiki page, or repository file renders as a real superscript link that jumps to a numbered footnotes section at the bottom, with a back-link to return to your place. It works the same way in Markdown files rendered on GitHub Pages.

GitLab renders footnotes the same way, and has for longer than GitHub — GitLab Flavored Markdown has included footnote support across issues, merge requests, and wiki pages for several major versions now.

Obsidian supports the same reference-and-definition syntax, plus its own shorthand: ^[an inline footnote written right here] creates a footnote without a separate definition elsewhere in the document at all. Both forms render as a small superscript number that shows the note content in a popover on hover or click, without navigating away from your place in the document.

This blog — and any Jekyll site using kramdown, which is Jekyll’s default Markdown processor — renders footnotes natively too. We checked this directly against kramdown’s actual output rather than assuming it from the spec: [^1] produces a real <sup>-wrapped jump link, and the definition becomes a proper <ol> entry with a reverse-footnote back-link, identical in shape to GitHub’s rendering. No plugin, no configuration flag — kramdown just handles it, which is presumably part of why footnote syntax proliferated on GitHub-adjacent sites in the first place.

Needs configuration — off by default

MkDocs, using the standard Python-Markdown processor, does not render footnotes out of the box. You need to explicitly enable the footnotes extension in mkdocs.yml:

markdown_extensions:
  - footnotes

Without it, [^1] and [^1]: text just print as literal characters — there’s no error, no warning, just plain text where you expected a footnote. If a MkDocs site you’re working on shows raw footnote syntax instead of rendered notes, this is almost always why.

Docusaurus, built on MDX, needs a comparable opt-in. Recent Docusaurus versions ship with GFM support (via remark-gfm) enabled in the default preset, which includes footnote parsing — but if you’re on an older config, a custom MDX pipeline, or you’ve deliberately swapped remark plugins, footnotes can silently stop working the same way they would on MkDocs without its extension. Worth a quick test render before you rely on them in a Docusaurus-based doc site, the same advice this blog’s MkDocs vs. Docusaurus vs. GitBook guide already gives for other GFM-adjacent features.

No support at all

Notion doesn’t recognize footnote syntax on import or paste — [^1] and its definition just come through as literal text sitting wherever they land, with no connection drawn between them. Our own Notion companion guide covers this as one of the format’s known casualties, and it’s also why the Markdown to Notion tool takes the deliberate step of inlining footnote text next to its reference before conversion — Notion never runs a footnotes step of its own, so if nobody flattens them first, they’re just lost.

Slack has no footnote handling anywhere in its formatting — not in the message composer, not via mrkdwn sent through the API, not in Block Kit. Same story in Jira and Confluence wiki markup: no equivalent syntax exists in either, native or otherwise. The practical workaround in all three, and what each platform’s companion guide on this blog recommends, is a plain parenthetical aside inline instead of a real footnote — there’s no rendering feature to fall back on.

Microsoft Word and HTML email don’t fare any better once you’re converting into them from Markdown, for a related but distinct reason: it’s not that Word or email clients can’t display footnotes (Word obviously has real native footnote support) — it’s that the client-side Markdown parsers doing the conversion (used by tools like our own Markdown to Word and Markdown to Email HTML converters) don’t implement the footnote extension, so [^1] passes through as literal bracket-and-caret text in the output rather than becoming a real Word footnote or an email-safe substitute.

Quick reference

Platform Footnotes render? Notes
GitHub Yes, natively Since September 2021
GitLab Yes, natively Longer-standing support than GitHub’s
Obsidian Yes, natively Also supports inline ^[...] shorthand
Jekyll (kramdown) Yes, natively Verified directly against kramdown’s own output
MkDocs Needs config Enable the footnotes extension in mkdocs.yml
Docusaurus Usually, via GFM Confirm your remark/MDX config includes it
Notion No Text passes through unlinked; import tools inline it instead
Slack No No equivalent in mrkdwn or Block Kit
Jira / Confluence No No wiki-markup equivalent in either
Word / Email HTML No (via conversion) The converting parser doesn’t expand the syntax

Cleaning up messy footnotes before you publish

None of the above matters much if your footnote numbering has drifted — which happens the moment you add, remove, or reorder a footnote in an existing document, since every reference and definition after that point needs updating in lockstep by hand. Our Footnote Organizer renumbers every footnote sequentially by the order it’s first referenced (not the order its definition happens to be written), collects all the definitions at the document’s end, and flags anything it can’t safely fix on its own — a reference with no matching definition, or a definition nobody ever referenced — rather than silently guessing.