Discourse Math Plugin

(Sam Saffron) #1

Repo: GitHub - discourse/discourse-math: Official MathJax support for Discourse



The math plugin uses MathJax (default) or KaTeX to render maths.

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%


This plugin only works with the latest version of Discourse with experimental markdown it enabled.

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

Future work

  • 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


Discourse for Academic Use Features (Done and to be Done)
Mathjax plugin install instructions?
CommonMark testing started here!
Discourse Preview Not Working
Is there a documentation for the math plugin (how to post complicated formulas etc.)
Plugin not work and show
Mathjax plugin install instructions?
LIST of plugins
Quick Messages Plugin
Installation problem with voting plugin

So, my vision of current equations state is:

  1. Bordering syntax for inline & block math is acceptable.
  2. Rendering can be done different ways, depending on developper’s preferences:
    • in browser (good for preview) / in node.js (for final)
    • to html (good for any displays) / to SVG (good at retina, better for static embed)
  3. NOT clear how to switch syntax between TeX / AsciiMath / …

The only unclear thing is syntax switch. Then i’ll be able to create “official” math plugin for markdown-it. In worst case, i’ll schedule plugin without (3) after some deadline.


(Mark McClure) #14

Hmm… I’m not sure where you’re getting those numbers. When I download and expand your repository, I get a 20MB folder on my hard drive - 19.9MB of which is MathJax.

Of course, you’re absolutely right that the core is quite manageable; it’s the ginormous number of little font files that take up all that room. While a single MathJax interaction uses only a fraction of these, it might still result in quite a few callbacks to the server which I’d prefer a CDN to handle.

I’d also mention one problem with server-side rendering, namely you lose some interactivity with the equations. In particular, you lose the Accessibility Features Extension. This is a big deal for those working in an academic setting where the Americans with Disabilities Act requires that course content be delivered in as accessible a format as possible.


(Sam Saffron) #15

From webpage test http://www.webpagetest.org/ running on a page on math.stackexchange that includes equations.

Well yeah, also the repo includes fallback fonts a gigantic amount of rendering options and so on and so on.

Which is easy, just set up a CDN per: Enable a CDN for your Discourse

Or do a simple PR to add a site setting to this plugin, I will probably get around to it.

That is a good point, when we do eventually add server side rendering we will make it options.


(Eli the Bearded) #16

About static image rendering, an acquaintance of mine wrote this:


Which is a garish webpage about a LaTeX syntax to PNG converter intended to run as a CGI, but also runnable as a command line tool. It’s been around a long time, long enough to iron out bugs, and is written in C for speed.


(Jason Sachs) #45

Usual MathJax issues: although I haven’t tried the plugin (yet – I need to twist some arms first in our internal Discourse instance), I would strongly argue against heuristics in parsing the $ character, in favor of one of the following:

  • per-post trigger of math (checkbox? but that’s intrusive in the UI… not sure if CommonMark allows directives like !math on or something)
  • configurability of MathJax delimeters – the \( and \) are common (recommended!) alternatives to $

Heuristics can be helpful, but when they are wrong then what do you do?


(Agustín Santiago Gutiérrez) #54

I had created an Issue on github for this, but the Issue Tracker seems to have disappeared.

“Same line math”, that is, things like $a+b$ using single $, do not display at all when inside a “spoiler” tag (The “hide details” thing).

For example

The following formula is shown as plain ascii $a+b+c$

However, the next one is perfectly rendered:

I have just updated to the most recent version of both discourse and discourse-math (1.9.0.beta15 and 0.9 , respectively) and this bug seems to always occur, no special configuration to reproduce, just put some latex within a “spoiler tag”.

1 Like

(Agustín Santiago Gutiérrez) #55

I emphasize, such a thing only happens inside these “hide details” elements. Outside of them, within a typical reply, latex shows perfectly both with $ and with $$.



I searched for posts that discusses the Asciimath syntax and didn’t see any.

From the MathJax Asciimath page:

By default, you mark mathematical expressions written in this form by surrounding them in “back-ticks”, i.e., ....

Suggest a combination of what is available today and a backtick to maintain some consistency with MathJax.

For example:

$` E=MC^2 `$



(Mark McClure) #67

I’ve just submitted a pull request to modify the plugin so that it can process input expressed in asciimath, as well as LaTeX. The code is on GitHub and (for a brief time only) you can see it in action on this temporary discourse instance.

I mention it here because, as you said:

I chose to delimit asciimath input with a single percent sign (%). The aciimath webpage indicates a preference for a backtick (`); that seems a poor choice because markdown typically uses this to denote inline code. There’s not a whole lot of other choices of single character delimiters that aren’t either very commonly used in math (like +/-/=) or captured by discourse for some special purpose (like @ or #). I went with the percent sign, in part, because it’s right next to the dollar sign used for TeX. Note that you can still use a percent sign in math input by escaping it with a backslash.


(Sam Saffron) #68

Hmm :thinking: what if we did something like %` some math ` , I know it is 2 keys but it would save us from escaping percents and we could have a block form with % triple backtick?

What do other markdown implementations do like math stack exchange etc?


(Mark McClure) #69

One thing that I like about the code the way I’ve set it up now is that it uses your original inlineMath function almost verbatim. I’ve just added a third argument to specify the delimiter - 36 for $ for LaTeX and 37 for % for asciimath. I rather like that simplicity and multi-purposing of code. Also, I’m a bit of a novice at this and not sure how much time it would take me to figure out to scan two symbols.

I’m definitely open to using some other single symbol; I’m just not sure of a better choice.

It would not be hard to set up a block form (I’d prefer to delimit it with %%) which would be passed to a div rather than a span. The typesetting itself, though, would be unaffected because asciimath itself does not distinguish between inline and display math. That’s why I didn’t specify a block form to begin with and I’m still not totally sure if it’s a good idea.

I don’t believe that math.stackexchange uses asciimath and I’m fairly active there. I honestly don’t know just how widely used it is. My own interest arises because I use Discourse to set up fora for college students and I’d like something that’s a bit more intuitive for them to use. I think the fact that asciimath is, to some degree, a “simpler” LaTeX supports the idea to use a single delimiter as well.

1 Like

(Sam Saffron) #70

Ok so I am fine to accept % but let’s make this optional default off with a site setting


(Mark McClure) #71

I can definitely do that!



It looks like the math formulas aren’t rendered in polls. They render in the preview of the polls, but not when the polls are actually posted. Is this something that can be fixed?

1 Like

(Daniel Hollas) #73

I wonder how dificult it would be to add KaTeX and whether smoebody is considering this. It seems that their code is maturing fast.

It would have an added benefit in our case to have the same rendering as Khan Academy on the forum about Khan Academy translations.

1 Like

(Jouni Seppänen) #74

I hacked together some code that will render the equations on the server:


There’s no error handling, and the font size doesn’t quite match the client-side version, but it seems to basically work in my development environment.


(Sam Saffron) #75

I really like the idea of this, should help performance quite a bit in some cases and starts unlocking email support! We still need to convert svg to png at some point for email.

Got to keep it optional for accessibility reasons though

@danekhollas I support a PR to add optional KaTeX


(Daniel Hollas) #76

Because plugin development is currently way above my league, I just wanted to try adding KaTex via custom theme, using the autorender Katex extension. It kinda worked, but I ran into an issue with supporting a single $ sign as a math delimiter.

It seems that even though I turned off the MathJax math plugin, the text enclosed in $ $ is converted to text inside <span class=math> and the dollar signs dissappear. Weirdly, I cannot reproduce this on META. Any ideas?

At the and of this Katex github issue, somebody reported a very similar problem, that was tracked down to Kramdown doing this auto conversion…


(Sam Saffron) #77

Yeah the auto render stuff if very likely going to be extremely janky on Discourse. We rely on proper hooks that “decorate” chunks of HTML as they are being added to the DOM. We got to do this thing properly.

Maybe @misaka4e21 can have a look at making KaTeX optional default off in the math plugin?