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 dollar-sign convention for math was never part of core Markdown, CommonMark, or even GitHub Flavored Markdown’s official spec. It’s a widely-adopted convention that individual platforms opt into (or don’t) on their own timeline, using different rendering engines with subtly different output. If you’ve ever pasted a formula that worked perfectly in one tool and showed up as raw LaTeX soup in another, this is why.

This guide covers which platforms actually render math natively, which need a plugin or app, which don’t support it at all, and the practical differences between the two rendering engines you’ll run into everywhere: MathJax and KaTeX. If you want the LaTeX syntax basics themselves rather than platform behavior, our complete guide to math expressions in Markdown covers that ground — and our Markdown Math Preview tool lets you check a formula renders correctly, live in your browser, before you paste it anywhere.

Native Support: GitHub, GitLab, Obsidian

Three platforms render $inline$ and $$block$$ math out of the box, no setup required.

GitHub added native math rendering in 2022, using MathJax. It works in READMEs, issues, pull requests, wiki pages, and Markdown files viewed in the repo browser — anywhere GitHub renders Markdown. Inline math uses $formula$ with no space touching the dollar signs; block math uses $$formula$$ on its own line(s). GitHub’s implementation is deliberately conservative: it supports the common LaTeX commands (fractions, exponents, Greek letters, sums, integrals, matrices) but not obscure packages, and it silently falls back to plain text for anything it can’t parse rather than showing an error.

GitLab has supported math rendering since GitLab 13.0 (2020), using KaTeX rather than MathJax. Syntax is the same $...$ / $$...$$ convention, and it works in issues, merge requests, wikis, and Markdown files. Because it’s KaTeX-based, GitLab’s rendering is closer to what our own Markdown Math Preview tool produces than GitHub’s MathJax output is — worth knowing if you’re maintaining docs that need to look consistent across both platforms.

Obsidian renders math natively in both edit and reading views, using MathJax under the hood (via the KaTeX-compatible subset it bundles). This is genuinely useful for people keeping research notes or technical vaults, since the formula renders live as you type rather than requiring a separate preview step. Obsidian’s math also plays well with its block-reference and embed system, so you can reference a specific equation from another note.

Needs a Plugin: Static Site Generators

Static site generators almost universally treat $ as literal text by default. Math support has to be added deliberately.

Jekyll (this blog’s own engine, and GitHub Pages’ default) has no built-in math support in kramdown. You need a plugin like jekyll-katex, or you can skip the plugin entirely and just load KaTeX’s or MathJax’s CSS/JS directly in your layout and let its auto-render script scan the page for $...$ after the page loads. The plugin approach pre-renders at build time (faster page loads, works without JavaScript); the client-side script approach is less setup but adds a render flash and a JS dependency.

Hugo has first-class support for this through render hooks in newer versions (Hugo 0.122+), letting you wire up KaTeX or MathJax rendering for passthrough math blocks without a third-party module — Hugo’s Goldmark-based Markdown renderer can pass $...$/$$...$$ through untouched for a script to pick up. Older Hugo setups typically use a shortcode or a theme-provided partial for the same effect. Either way, it’s opt-in configuration, not default behavior.

Docusaurus supports math via two remark/rehype plugins — remark-math and rehype-katex — added to your docusaurus.config.js. This is a well-documented, one-time setup, and once it’s in place, $...$/$$...$$ in any .md/.mdx file just works. Because it’s explicitly KaTeX-based, output is consistent with GitLab’s and with our Markdown Math Preview tool.

MkDocs similarly needs a math extension (pymdownx.arithmatex from the PyMdown Extensions package is the common choice) plus a KaTeX or MathJax script reference in your theme, following the same “opt-in, one-time config” pattern as Hugo and Docusaurus.

Real Feature, Different Trigger: Notion

Notion supports LaTeX math, but not via the $...$ dollar-sign convention as your primary path — it’s a block/inline type you insert with the /equation (or /math) slash command, or by typing $$ and pressing space to trigger an inline equation editor. Once inserted, you type LaTeX inside that dedicated equation block, and Notion renders it with its own KaTeX-based engine. If you paste a Markdown file containing raw $...$ text into Notion, it generally will not auto-convert that into a rendered equation the way headings or bold text get auto-converted on paste — you get literal dollar-sign text, and need to manually convert it via the equation block. This trips up anyone assuming Notion behaves like GitHub here; the feature exists, but the entry point is different.

Needs a Marketplace App or Doesn’t Support It: Confluence, Jira, Slack

Confluence has no native $...$ math rendering in its standard editor. Cloud users can add a marketplace app (several LaTeX-rendering add-ons exist) that adds a macro for inserting rendered formulas, but that’s a dedicated macro/insert flow, not something that recognizes dollar-sign syntax typed inline. If you paste Markdown with LaTeX math into Confluence via the /markdown panel (see our Confluence guide for how that panel behaves generally), the math syntax passes through as literal text.

Jira has no math rendering at all in its wiki markup or in the modern rich-text editor — there’s no macro, no plugin ecosystem equivalent to Confluence’s for this specific feature. If your team needs formulas in Jira tickets, the common workaround is rendering the equation elsewhere (including with our tool) and pasting it in as an image.

Slack doesn’t support math rendering anywhere — not in the message composer, not via the API/Block Kit, not with a workaround short of posting a pre-rendered image. A message containing $E = mc^2$ displays as exactly that literal text. Given mrkdwn’s generally limited formatting (see our Markdown to Slack guide for the full picture), this isn’t surprising, but it catches people off guard the first time.

MathJax vs. KaTeX: Why the Same Formula Can Look Different

Two rendering engines account for nearly every platform above, and they’re not pixel-identical:

  • MathJax is the older, more complete implementation — broader LaTeX command coverage, including several packages and less-common symbols, at the cost of being noticeably heavier and historically slower (modern versions have closed much of that gap, but it’s still the heavier of the two). GitHub and Obsidian use MathJax or a MathJax-derived engine.
  • KaTeX is faster (it renders synchronously, without MathJax’s original asynchronous typesetting pass) and covers the large majority of everyday math notation, but it deliberately supports a smaller command set — some advanced LaTeX packages used in academic papers will throw a parse error in KaTeX that a full MathJax/LaTeX setup would render fine. GitLab, Docusaurus, MkDocs (with the common config), Notion, and our own Markdown Math Preview tool are all KaTeX-based.

In practice this means a formula that renders cleanly on GitHub isn’t guaranteed to look byte-for-byte identical on GitLab, and a formula relying on an obscure package might work in one and throw an error in the other. For everyday formulas — fractions, exponents, Greek letters, sums, integrals, standard matrices — you won’t notice a difference. For anything exotic, test on your actual target platform rather than assuming.

Quick Reference

Platform Math support Engine How it’s triggered
GitHub Native MathJax $...$ / $$...$$ anywhere Markdown renders
GitLab Native KaTeX $...$ / $$...$$ anywhere Markdown renders
Obsidian Native MathJax-derived $...$ / $$...$$, live in edit and reading views
Notion Real feature, different entry point KaTeX /equation block or $$ + space, not passive $...$ paste
Jekyll / GitHub Pages Needs plugin or manual script Your choice (KaTeX or MathJax) Plugin (e.g. jekyll-katex) or client-side auto-render script
Hugo Needs render hook or theme support Your choice Goldmark passthrough + KaTeX/MathJax script
Docusaurus Needs plugin config KaTeX remark-math + rehype-katex
MkDocs Needs extension Your choice pymdownx.arithmatex + theme script
Confluence Marketplace app only Varies by app Dedicated macro/insert, not inline $...$
Jira Not supported — No native option; paste as image
Slack Not supported — No native option; paste as image

Practical Takeaways

If you’re writing math-heavy documentation and want it to render without any setup on the reader’s end, GitHub, GitLab, or Obsidian are your only truly zero-configuration options. If your docs live on a static site generator, budget time for the one-time plugin setup — it’s usually a few lines of config, but it’s not automatic, and a Markdown file with unrendered $...$ littered through it looks broken to anyone who stumbles on the raw source before the setup is done. And if your formulas are headed to Confluence, Jira, or Slack, plan on images rather than fighting a platform that was never going to render LaTeX in the first place.

Whichever platform you’re targeting, it’s worth checking the formula renders the way you expect before you commit it to a README or a ticket — a misplaced brace or an unsupported command shows up as a parse error or, worse, silently wrong output. Our Markdown Math Preview tool renders both inline and block math live as you type, using KaTeX, and shows the exact parser error if something doesn’t parse — a fast sanity check before you paste a formula into any of the platforms above.