Math support

[SamyPesse]

I think that it would be really cool to support MathJAX for writing math formulas.

[ramnathv]

👍 I would really appreciate if this feature could be added. For the interim, is there a simple workaround, other than copy pasting the required mathjax code on every page?

[pkra]

Peter from the MathJax team here. Feel free to ping me know if we can help with any questions.

[SamyPesse]

Hi @pkra, is there any way we can do the HTML generation in node.js so that we don't depend on client-side operation?

[pkra]

@SamyPesse that's a complex question. The answer is probably "no" but it really depends on what you're after.

MathJax is highly modular both on input and output format (and internally, actually). On the input side, MathML, TeX and asciimath syntax are supported. (The issue is called "math support" but it's not clear if multiple input options are needed). On the output side, MathJax can generate HTML/CSS, SVG or MathML rendering (the internal format is basically MathML).

The HTML/CSS and SVG output depend strongly on the client (e.g. viewport size for linebreaking, CSS inheritance). The HTML/CSS output is too unstable to generate ahead of time (there are too many hacks we have to do to work around browser bugs and limitations). The SVG output can be generated but will also loose functionality. Generating MathML is best IMHO, but it means you'll still want to run MathJax on clients (purely as a MathML polyfill; and if you're happy with Firefox's and Safari's MathML support and rendering quality you won't need it there).

The bad news is that MathJax currently won't run in a pure nodejs environment (basically because 5 years ago that wasn't important). We're planning to remedy that in the near future (this quarter) so that at least MathML and SVG generation can work in nodejs. In the mean time you could try out mathoid which uses phantomjs as a stop gap.

[ramnathv]

My quick hack to make it work was to save this snippet as mathjax.html in the includes folder and including it in the page template. It works great.

<!-- MathJax: Fall back to local if CDN offline but local image fonts are not supported (saves >100MB) -->
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    tex2jax: {
      inlineMath: [['$','$'], ['\\(','\\)']],
      processEscapes: true
    }
  });
</script>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/2.0-latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

[pkra]

Which markdown converter is used in gitbook? Clashes with TeX syntax are inevitable but some are better than others. stackedit might be a good example for how to deal with this.

[SamyPesse]

GitBook uses https://github.com/chjj/marked. I'll take a look at all of this.

[jbryer]

@ramnathv How do you include the mathjax.html file in the pages template? I don't see where that is. Thanks

[jbryer]

I figured it out. I needed to create my own copy of the theme directory and modify the layout.html (probably works in page.html too). Here is the command to include: {% include "includes/mathjax.html" %}

One issue however, underscores seem to be converted to tags. Escaping them with a backslash (i.e. _) takes care of this. I have used other markdown tools and have not had this problem.

[SamyPesse]

@pkra Can you help me for something?

I'm working on the new plugin architecture and I built a MathJAX plugin that will be integrated as default: https://github.com/GitbookIO/plugin-mathjax

But I need to re-run the processing of the page when "page.change" event happened: https://github.com/GitbookIO/plugin-mathjax/blob/master/book/plugin.js#L11

I didn't find in the documentation how to do that.

[ramnathv]

I think you need to use Mathjax.Hub.Rerender. See the discussion here

[pkra]

@SamyPesse basically, what @ramnathv said; see http://docs.mathjax.org/en/latest/typeset.html.

(I don't know enough about the internals of gitbook to suggest optimizations. E.g. it might be worth restricting the Rerender call to the new content to prevent unnecessary processing of e.g. math in the menu; e.g. if you prefetch content, then MathJax could potentially render ahead of the reader accessing the new content. etc)

[ramnathv]

I agree with @pkra. The page I linked to is contains a sample implementation for revealjs, where Rerender is used to selectively render only the math on the current slide, based on an event that is fired on entering a slide. I haven't see gitbook internals, but I believe, if there is access to the page content that changes on entry to a page, then passing that to Rerender should do the trick.

[pkra]

An early version of the MathJax-node tool I mentioned earlier is now public at https://github.com/mathjax/mathjax-node. Pre-processing MathJax input into MathML (or SVG) would solve other issues such as #295.