[{"data":1,"prerenderedAt":64},["Reactive",2],{"blog-post-markdown-footnotes-across-platforms":3},{"slug":4,"title":5,"description":6,"excerpt":7,"date":8,"category":9,"author":10,"keywords":11,"readingMinutes":12,"html":13,"headings":14,"tools":34,"related":39},"markdown-footnotes-across-platforms","Markdown Footnotes Across Platforms: Where They Actually Render","GitHub, GitLab, Obsidian, and this very blog render [^1] footnotes natively — Notion, Slack, Jira, and Confluence don't support them at all. A platform-by-platform reference for where footnote syntax actually works.","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…","2026-09-25","Reference","Matthew Rathbone","markdown footnotes across platforms, github footnotes, gitlab footnotes, notion footnotes, obsidian footnotes support",5,"\u003Cp>Footnote syntax — a reference marker like \u003Ccode>[^1]\u003C/code> in the body text, paired with a definition \u003Ccode>[^1]: The actual note.\u003C/code> elsewhere in the document — looks the same everywhere you write it. Whether it \u003Cem>renders\u003C/em> 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.\u003C/p>\n\u003Cp>If you haven't used footnote syntax before, our \u003Ca href=\"/blog/footnotes-in-markdown\">footnotes in Markdown guide\u003C/a> covers the basic syntax first. If you're doing heavier academic-style citation work, see our \u003Ca href=\"/blog/markdown-citations-and-references-guide\">citations and references guide\u003C/a>. This post is specifically about the one thing those guides don't fully settle: does your renderer actually turn \u003Ccode>[^1]\u003C/code> into a footnote, or not.\u003C/p>\n\u003Ch2 id=\"native-support-no-configuration-needed\">Native support, no configuration needed\u003C/h2>\n\u003Cp>\u003Cstrong>GitHub\u003C/strong> added real footnote rendering in September 2021 — this is worth calling out explicitly, because plenty of older Markdown content (including, until this post, \u003Ca href=\"/blog/footnotes-in-markdown\">our own footnotes guide\u003C/a>) still says GitHub doesn't support them, which was true before that date and isn't anymore. Today, \u003Ccode>[^1]\u003C/code> 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.\u003C/p>\n\u003Cp>\u003Cstrong>GitLab\u003C/strong> 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.\u003C/p>\n\u003Cp>\u003Cstrong>Obsidian\u003C/strong> supports the same reference-and-definition syntax, plus its own shorthand: \u003Ccode>^[an inline footnote written right here]\u003C/code> 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.\u003C/p>\n\u003Cp>\u003Cstrong>This blog\u003C/strong> — 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: \u003Ccode>[^1]\u003C/code> produces a real \u003Ccode><sup>\u003C/code>-wrapped jump link, and the definition becomes a proper \u003Ccode><ol>\u003C/code> 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.\u003C/p>\n\u003Ch2 id=\"needs-configuration--off-by-default\">Needs configuration — off by default\u003C/h2>\n\u003Cp>\u003Cstrong>MkDocs\u003C/strong>, using the standard Python-Markdown processor, does \u003Cem>not\u003C/em> render footnotes out of the box. You need to explicitly enable the \u003Ccode>footnotes\u003C/code> extension in \u003Ccode>mkdocs.yml\u003C/code>:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-yaml\">\u003Cspan class=\"hljs-attr\">markdown_extensions:\u003C/span>\n  \u003Cspan class=\"hljs-bullet\">-\u003C/span> \u003Cspan class=\"hljs-string\">footnotes\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>Without it, \u003Ccode>[^1]\u003C/code> and \u003Ccode>[^1]: text\u003C/code> 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.\u003C/p>\n\u003Cp>\u003Cstrong>Docusaurus\u003C/strong>, built on MDX, needs a comparable opt-in. Recent Docusaurus versions ship with GFM support (via \u003Ccode>remark-gfm\u003C/code>) 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 \u003Ca href=\"/blog/mkdocs-vs-docusaurus-vs-gitbook\">MkDocs vs. Docusaurus vs. GitBook guide\u003C/a> already gives for other GFM-adjacent features.\u003C/p>\n\u003Ch2 id=\"no-support-at-all\">No support at all\u003C/h2>\n\u003Cp>\u003Cstrong>Notion\u003C/strong> doesn't recognize footnote syntax on import or paste — \u003Ccode>[^1]\u003C/code> and its definition just come through as literal text sitting wherever they land, with no connection drawn between them. Our own \u003Ca href=\"/blog/markdown-for-notion-what-actually-works\">Notion companion guide\u003C/a> covers this as one of the format's known casualties, and it's also why the \u003Ca href=\"/tools/markdown-to-notion\">Markdown to Notion tool\u003C/a> 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.\u003C/p>\n\u003Cp>\u003Cstrong>Slack\u003C/strong> 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 \u003Cstrong>Jira\u003C/strong> and \u003Cstrong>Confluence\u003C/strong> 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.\u003C/p>\n\u003Cp>\u003Cstrong>Microsoft Word\u003C/strong> and \u003Cstrong>HTML email\u003C/strong> don't fare any better once you're converting \u003Cem>into\u003C/em> 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 \u003Ca href=\"/tools/markdown-to-docx\">Markdown to Word\u003C/a> and \u003Ca href=\"/tools/markdown-to-email-html\">Markdown to Email HTML\u003C/a> converters) don't implement the footnote extension, so \u003Ccode>[^1]\u003C/code> passes through as literal bracket-and-caret text in the output rather than becoming a real Word footnote or an email-safe substitute.\u003C/p>\n\u003Ch2 id=\"quick-reference\">Quick reference\u003C/h2>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Platform\u003C/th>\n\u003Cth>Footnotes render?\u003C/th>\n\u003Cth>Notes\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>GitHub\u003C/td>\n\u003Ctd>Yes, natively\u003C/td>\n\u003Ctd>Since September 2021\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>GitLab\u003C/td>\n\u003Ctd>Yes, natively\u003C/td>\n\u003Ctd>Longer-standing support than GitHub's\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Obsidian\u003C/td>\n\u003Ctd>Yes, natively\u003C/td>\n\u003Ctd>Also supports inline \u003Ccode>^[...]\u003C/code> shorthand\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Jekyll (kramdown)\u003C/td>\n\u003Ctd>Yes, natively\u003C/td>\n\u003Ctd>Verified directly against kramdown's own output\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>MkDocs\u003C/td>\n\u003Ctd>Needs config\u003C/td>\n\u003Ctd>Enable the \u003Ccode>footnotes\u003C/code> extension in \u003Ccode>mkdocs.yml\u003C/code>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Docusaurus\u003C/td>\n\u003Ctd>Usually, via GFM\u003C/td>\n\u003Ctd>Confirm your remark/MDX config includes it\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Notion\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003Ctd>Text passes through unlinked; import tools inline it instead\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Slack\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003Ctd>No equivalent in mrkdwn or Block Kit\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Jira / Confluence\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003Ctd>No wiki-markup equivalent in either\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Word / Email HTML\u003C/td>\n\u003Ctd>No (via conversion)\u003C/td>\n\u003Ctd>The converting parser doesn't expand the syntax\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Ch2 id=\"cleaning-up-messy-footnotes-before-you-publish\">Cleaning up messy footnotes before you publish\u003C/h2>\n\u003Cp>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 \u003Ca href=\"/tools/markdown-footnotes\">Footnote Organizer\u003C/a> 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.\u003C/p>\n\u003Ch2 id=\"related-reading\">Related reading\u003C/h2>\n\u003Cul>\n\u003Cli>\u003Ca href=\"/blog/footnotes-in-markdown\">How to Use Footnotes in Markdown\u003C/a> — the basic syntax\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-citations-and-references-guide\">Markdown Citations and References\u003C/a> — academic citation styles and bibliography tools\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-platform-compatibility-guide\">Markdown Platform Compatibility Guide\u003C/a> — the broader picture beyond just footnotes\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/why-your-markdown-isnt-rendering\">Why Your Markdown Isn't Rendering\u003C/a> — troubleshooting other silent syntax failures\u003C/li>\n\u003C/ul>\n",[15,19,22,25,28,31],{"id":16,"text":17,"level":18},"native-support-no-configuration-needed","Native support, no configuration needed",2,{"id":20,"text":21,"level":18},"needs-configuration--off-by-default","Needs configuration — off by default",{"id":23,"text":24,"level":18},"no-support-at-all","No support at all",{"id":26,"text":27,"level":18},"quick-reference","Quick reference",{"id":29,"text":30,"level":18},"cleaning-up-messy-footnotes-before-you-publish","Cleaning up messy footnotes before you publish",{"id":32,"text":33,"level":18},"related-reading","Related reading",[35,36,37,38],"markdown-to-notion","markdown-to-docx","markdown-to-email-html","markdown-footnotes",[40,50,57],{"slug":41,"title":42,"description":43,"excerpt":44,"date":45,"category":46,"author":47,"keywords":48,"readingMinutes":49},"markdown-math-rendering-across-platforms","Markdown Math Rendering Across Platforms: Where LaTeX Actually Works","The $...$ / $$...$$ LaTeX convention for math in Markdown looks identical everywhere, but whether it renders at all — and which engine renders it — varies enormously across GitHub, GitLab, Obsidian, Notion, Jekyll, Hugo, Confluence, and Slack. Here's what's real.","Wrap a formula in dollar signs — $E = mc^2$ — and on some platforms you get a beautifully typeset equation. On others you get the literal text $E = mc^2$ sitting there unrendered, because the…","2026-08-21","workflows","Matt Rathbone","markdown math rendering, latex markdown platforms, katex vs mathjax, github math support, notion math equations, jekyll math plugin, hugo katex, confluence math",8,{"slug":51,"title":52,"description":53,"excerpt":54,"date":55,"category":46,"author":47,"keywords":56,"readingMinutes":49},"markdown-callouts-admonitions-across-platforms","Markdown Callouts and Admonitions Across Platforms: What Actually Renders","GitHub's > [!NOTE] alert syntax, Obsidian's callouts, and MkDocs's admonition extension all look like variations on a theme — but they're three genuinely different syntaxes that mostly don't cross-render. Here's what works where.","Type > [!NOTE] into a Markdown file and on GitHub you get a styled, icon-prefixed callout box. Paste that exact same text into a plain CommonMark renderer, a Jekyll site with no plugin, or an…","2026-08-28","markdown callouts, github alerts, obsidian callouts, mkdocs admonitions, docusaurus admonitions, markdown warning box across platforms",{"slug":58,"title":59,"description":60,"excerpt":61,"date":62,"category":46,"author":47,"keywords":63,"readingMinutes":49},"markdown-image-sizing-alignment-across-platforms","Markdown Image Sizing and Alignment Across Platforms: What Actually Works","Wrapping an image in a sized, centered \u003Cimg> tag works great in GitHub — but paste that same Markdown into Notion or Slack and the HTML just vanishes. Here's which platforms honor inline HTML for images, which have their own separate syntax, and which need attachments instead.","Standard Markdown's image syntax — — has no way to control size or alignment. There's no width=, no center, nothing. So the moment you need a smaller image, or one centered on the page instead of…","2026-09-04","markdown image size, markdown image alignment, resize image markdown, center image markdown, obsidian image size, notion image markdown, markdown image html platforms",1792184947114]