Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Port MathJax support from gollum to jekyll #199

mreid opened this Issue Aug 14, 2010 · 19 comments


None yet

mreid commented Aug 14, 2010

I noticed that gollum has MathJax support, which looks great. Any chance of "stealing" this and adding it to Jekyll?

kikito commented Aug 16, 2010

Unless I'm understanding this incorrectly, since MathJax is a javascript lib, you can just copy the MathJax folder to your Jekyll and then put this on any page (or layout)where you want MathJax included:

<script type="text/javascript" src="path-to-MathJax/MathJax.js"></script>

Then you should be able to use MathJax directly.


mreid commented Aug 17, 2010

The trick is that any equations need to be left untouched by markdown/textile processing so that they appear "raw" in the HTML that the MathJax script is applied to. For an idea of what can go wrong, the equation $(x_i, y_i)$ will become $(x<em>i, y</em>i)$ when rendered with markdown.

The code in gollum uses a simple hashing trick to protect equations before markdown is applied.

kikito commented Aug 17, 2010

I'm not that familiar with markdown. In textile, there's a notextile command that will solve that quite easily.


A cursory google search throws this stackoverflow page:


Apparently, markdown will not go inside any div. I'm guessing it will also respect your code if you put it inside a span.


mreid commented Aug 18, 2010

That is one possible solution but has a couple of drawbacks from my point of view. First, it makes me do the work (adding extra markup) instead of the computer. And second, the current behaviour of Jekyll is that is handles unadorned equations (i.e., not wrapped in any extra commands) in plain text and correctly renders them to images and inserts them into HTML.

Having written a lot of posts which involve equations, I think the way gollum does things at the moment is the better way to go (i.e., not requiring the user to tell markdown/textile to ignore chunks of input) and think jekyll would benefit from this approach to MathJax as well.

kikito commented Aug 18, 2010

MathJax defines equations either on MathML, which both textile and markdown will respect, or TeX-like (regular text encoded between [ and ]), which requires an additional

to work correctly (or a noscript section in textile). I personally don't see the need of those aditional 11 characters as a big lose in efficiency. I'd even argue that enclosing everything on a div or span makes more sense from a semantic web point of view. The MathJax sample pages would be more semantically correct if they included those extra divs.

But the deal breaker for me is possible trouble with other people. People that blogged about TeX could have trouble if the textile renderer did anything fancy with [ and ]). So I don't think this should be a "mainstream" change.

If you are hosting your own Jekyll server (instead of using github pages) you probably can write your own renderer as a plugin - a markdown renderer that detects the [ and ] and skips rendering.


mreid commented Aug 19, 2010

This argument is getting tedious. I have simply stated that this feature would be useful for my needs, perhaps others. I have written over 50 posts using math-enabled Jekyll and dozens of pages. I contributed to the early Jekyll codebase adding maruku support and option parsing. You are trying to argue that your imagined downsides outweigh what would be concrete benefits for me.

Math rendering of any type is optional in Jekyll already. I was never arguing for a MathJax version that was on by default.

If you "personally don't see the need of those additional 11 characters as a big lose in efficiency" why are you using Textile at all? Why not write your posts in HTML?

(For the record, markdown already turns [ ] into plain [ ] so if you want to write TeX source in a markdown document you would have to surround it in a code block anyway.)

Jekyll is one of the few blogging engines that offers good support for math. If it offered (optional) MathJax support it would strengthen this advantage.

kikito commented Aug 19, 2010

I don't use Markdown since I prefer textile. From time to time, I have to write tiny bits of html on it - and other times I have to use notextile. And that is just fine, for my case. I use plain html on the layout files.

The thing that worried me was not the MathJax support enabled by default, but the automatic disabling of markup rendering between [ and ]. Say that someone tried to write something like this - I'm going to write on textile since it is the one I know:

Your TeX comments must begin with *\[*.
You can put "TeX commands":http://www.tug.org/utilities/plain/cseq.html
inside, but you *must* finish with *\]*.

There are some textile commands between the [\ and ], and normally people would want those to be rendered using the textile renderer.

The MathJax should be optional, but my point is that this "markup deactivation" must be part of that optionality too.

I'm sorry if this is getting tedious. I'm just trying to help.

rcfox commented Sep 6, 2010

Under /MathJax/config/MathJax.js, there's a variable called "skipTags". If you remove "code" from the list of tags, then you can simply put your LaTeX within backticks (``).

With the <div> method, Maruku barfs when you do &= in the LaTeX, even though it's not supposed to be parsing inside of the <div>, so you have write &amp; instead.

@rcfox: I tried excluding "code" from the list skipTags, but that doesn't seem to do the trick--mathjax still doesn't parse the <code>$$ foo $$</code> blocks anyway. Removing the surrounding code tags, results in correct rendering though.

Mathjax bug?

rcfox commented Feb 11, 2011

Are you writing <code>$$ foo $$</code>, or $$ foo $$ ? I'm not sure if it should matter, but I used the latter.

I used the latter too. The problem wasn't with MathJax refusing to parse code blocks, but with the way in which I specified the skipTags variable in the MathJax configuration. Check out this page for the solution: https://github.com/mathjax/MathJax/issues/issue/70/#comment_759050

i didn't want to give up my tag, so I wrote a small liquid tag to address this issue instead:


It's still a bit cumbersome for the inline math, but it does the job.

I hack my way around it by writing my math like $$ example $$, then setting my MathJax configuration as

    tex2jax: {
        skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'] // removed 'code' entry
MathJax.Hub.Queue(function() {
    var all = MathJax.Hub.getAllJax(), i;
    for(i = 0; i < all.length; i += 1) {
        all[i].SourceElement().parentNode.className += ' has-jax';

where the 'has-jax' rule resets any other styles applied to the <code> tag with something like

code.has-jax {font: inherit; font-size: 100%; background: inherit; border: inherit;}

It's hideous, but it works :)

dsanson commented Aug 7, 2011

Pandoc has built-in MathJax support. I use the pandoc-ruby branch of my fork of jekyll with MathJax, and it works well without any special tweaks or hacks.

fommil commented Oct 19, 2012

@stygstra I'm trying to get MathJax to work with a self-processed Markdown file. How can I send your configuration to the CDN version of MathJax? http://docs.mathjax.org/en/latest/platforms/index.html

fommil commented Oct 19, 2012

Nevermind, worked it out: add this to top of markdown file http://pastie.org/5084969

hardywu commented Dec 28, 2012

I am loading the mathjax from cdn as an additional script tag with a local config js file provide above. What bothers me is that it always take more time 10 sec to compile the latex code during what people see an ugly post with latex commands messing around.

The best way to do is that jekyll do the compilation using mathjax to mathml into the static pages.

Or there is another package called textmath can do the same thing.


parkr commented Mar 17, 2013


@parkr parkr closed this Mar 17, 2013

With kramdown it works fine: http://cirosantilli.github.io/jekyll-cheat/#math

I also prefer server side rendering for the speed.

@jekyllbot jekyllbot locked and limited conversation to collaborators Feb 27, 2017

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.