Discourse Math

:discourse2: Summary Discourse Math uses MathJax (default) or KaTeX to render maths in your Discourse forum.
:hammer_and_wrench: Repository Link https://github.com/discourse/discourse-math
:open_book: Install Guide How to install plugins in Discourse


You can render blocks of maths by wrapping with $$


You can render inline math by wrapping with a single $ like so: $E=mc^2$.

Discourse math uses a heuristic to ensure that sentences such as: “I spent 20$ and another 100$” do not get converted.

When using MathJax, you can also enable asciimath processing which uses % as a delimiter: %E=mc^2%


:warning: This plugin is disabled by default, after installing be sure to enable it via site settings.



  • We would love to support server-side rendering, there is already an online sample.


What about the old plugin?

There is a plugin maintained by @Kasper/ @masda70 called Discourse MathJax. This plugin is a ground up re-write to support the new markdown it engine. The main differences are:

  • It is much stricter about block and inline syntax, only $ and $$ blocks are supported

  • It embeds MathJax or KaTeX renderer so you do not need to use a CDN

  • It only loads the math renderer if it detects equations on the page.

  • It surgically applies renderer as opposed to performing full page scans.

  • It is well specified using specs


Continuing my PR series adding features to the Katex implementation, I added support for equation labelling and referencing (more Mathjax compatibility):

I enabled it in the Discourse code too as seen in the commit. This adds support for \tag, \label, \ref, \eqref so equations can be labeled and referenced (references are clickable too). This is another feature that Katex disables by default. Enabling it brings the Katex implementation in DIscourse more inline with Mathjax. My previous PR added support for persistent macros.

Tested and working in latest Discourse stable.


Made another PR, this time to add something I always wanted: proper copy/paste of latex code: highlight rendered latex in a post, paste in editor and get proper latex, see:

@sam The Discourse “quote” functionality is also improved, but has a quirk: while it does insert the proper latex code for the highlighted equation (hence I take the Discourse code relies on clipboard features), it still adds the plain-text version as well and does so twice, which is clearly a bug. I can look into this and try to fix it but I could use a pointer from you for the Discourse code that handles the “Quote” feature for highlighted text to save me some time.


Oh, how timely, maybe the work @martin did here can help answer this?

1 Like

Not sure if it’s related to my fix that @sam pointed out, but I can check. Would you mind providing some Latex code that I can use to try and reproduce? A screen recording of what is happening would be very useful too.

1 Like

Hi Team,

This topic seems related MathJax seems broken in v2.9.0.beta5 - bug - Discourse Meta

Not sure if related with this line discourse-math/discourse-math-mathjax.js at main · discourse/discourse-math · GitHub