Discourse Math Plugin


(Sam Saffron) #1

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



The math plugin uses MathJax 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 MathJax treatment.


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.

  • We need to discuss a syntax for asciimath. Once a syntax is picked support will be very easy to add.

  • We are open to adding optional support for Katex.

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 so you do not need to use a CDN

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

  • It surgically applies MathJax 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!
Is there a documentation for the math plugin (how to post complicated formulas etc.)
Discourse Preview Not Working
Plugin not work and show
Mathjax plugin install instructions?
Installation problem with voting plugin

@sam, since i plan to implement “something about math” in nodeca, there are couple of questions about your experience with mathjax.

  1. To display page fast and avoid reflows, it would be nice to have “static” content, with predefined equations size. Is it realistic to generate self-sufficient SVGs? Those could be embedded into generated html.
  2. Did you tried KaTeX? (i don’t know anything about it except that it’s faster than mathjax in their demo)

(Mark McClure) #5

This sounds like a great idea! I hope to take it for a spin in a couple weeks.

I wonder, though - you write:

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

Is there an option so that you can use a CDN? There’s a lot of good reasons to do so. I hate to serve so many fonts from my little server when CloudFlare is happy to do so.

(Sam Saffron) #6

I mean, no need to use a third party CDN, it will use the discourse configured CDN just fine

(Jeff Atwood) #7

I could see wanting a third party CDN for MathJax as it is ginormous, when you need it you likely need it on every single page, and and like jquery it is already centrally hosted a bunch of places.

(Felix Freiberger) #8

I’d like to give a ginormous thanks to @sam!

I’ve used the old MathJax plugin before and did hate to see it break regularly. It’s amazing to see this turn into a new, official plugin :smiley:

Thank you for making Discourse a lot more awesome for academic use :heart:

Contributor Interviews – Felix "fefrei"
(Sam Saffron) #9

I started looking at SVG, but really did not like the rendering at all, it just looks less good that the HTML it renders.

Compare this HTML


The difference is minor but it just looks fuzzier and less readable to me.

However, you can generate HTML + CSS directly on the server side and embed into the page, then, as long as the font is ready you can avoid reflows and not even include MathJax in the initial payload. This is the approach we will eventually take.

I avoided it, when I researched it I found that it has a limited subset of math support that people are not happy with.


Looking at:

Function Support in KaTeX · Khan/KaTeX Wiki · GitHub


History for Function Support in KaTeX · Khan/KaTeX Wiki · GitHub

It looks like they have made tons of progress since this was first discussed on those sites, however, there there are still gaps with MathJax and there is little point to include it if you can render MathJax anyway on the server side.

(Sam Saffron) #10

Sort of, MathJax weighs 80K and then you need a few fonts. It adds up to about 130K or so.

Our Ember+jQuery payload that everyone needs comes in at a similar size and we have no support for an external CDN here.

I am not against adding the options for an external CDN here, but I don’t think its an enormous drama, especially once we get server side rendering going (which would half its payload cause all you need is fonts)


Thanks for info!

I think, that’s because HTML use fonts for display content. Those have hinting + subpixel rendering. But this difference should be less notable on retina display. Did you used normal or HiDPI monitor? If you have no HiDPI monitor - try to compare rendered output at mobile phone.

(Sam Saffron) #12

Yeah I have a standard monitor here not a HiDPI, I am pretty sure SVG will be way better on retina.


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.

(Nordize) #17

I’m running 1.9.0.beta4 and I can’t see this plugin anywhere in setting to enable. I did enable the experimental markdown it setting. I have the older MathJax plugin (which currently doesn’t work) which I disabled. Any clues?

Also, are things like \align and other math environments working? Your first post said only $ and $$ supported, but one can hope). That’s one thing I liked about the older plugin.

(Nordize) #18

I’d be grateful for ideas on how to make this new plugin work … currently it looks like it’s not even there. I run 1.9.0.beta4 which was upgraded from 1.8 and which had (still has) the older mathjax plugin, and which I now disabled. There is nothing in the settings about a different math or tex plugin.

Has anyone been in the above scenario (upgrade with mathjax plugin enabled) and got the newer math plugin working?

(Rafael dos Santos Silva) #19

Well, did you install the plugin? As in, add it to app.yml and rebuild.

(Nordize) #20

The first post said

which I took as meaning that it’s included by default and only needs to be enabled in site settings (I took “after installing” to mean “after installing discourse”). I didn’t find actual instructions to install this plugin. Is this what’s needed?

    - exec:
        cd: $home/plugins
          - git clone https://github.com/discourse/docker_manager.git
          - git clone https://github.com/discourse/discourse-math.git

If yes, then you guys may wish to update the first post with this info, for those slower folks like me …

(Nordize) #22

You may also wish to state for those who upgrade from other/older mathjax plugins that a full posts rebake is needed, i.e.

./launcher enter app
rake posts:rebake

All my posts containing latex were not showing markup until I rebaked them.

(xiasummer) #23

I think the plugin is not good.

  • I find if $\frac{1}{2}$ such thins with characters close to the $, it will not take effect. why should we always have a space before the first $ and fater the last $??

  • Big Problem the $$\frac{1}{2}$$ will not take effect! Only


Will take effect. You see, I usually put my notes from other files to Discourse! If it is like this, most of my notes from latex will not have the right effect. Do I have to change all my notes one by one??