Local mathjax with mkdocs

Question

I'd like to use MathJax with Mkdocs on a computer which does not have access to the internet, I can't therefore just call the Mathjax CDN.

Config

mkdocs.yml:

site_name: My Docs

extra_javascript:
  - 'javascripts/MathJax-2.7.5/MathJax.js'
  - 'javascripts/MathJax-2.7.5/extensions/MathMenu.js'

markdown_extensions:
  - pymdownx.arithmatex

File structure

project/
    docs/
        javascripts/
            MathJax-2.7.5/
                ...
    mkdocs.yml

Following Mathjax's documentation, the folder /MathJax-2.7.5/ contains the whole uncompressed archive.

Problem

Running mkdocs serve I get the following errors:

[E 181003 11:32:04 web:1591] Uncaught exception GET /javascripts/MathJax-2.7.5/extensions/MathMenu.js (127.0.0.1)
    HTTPServerRequest(protocol='http', host='127.0.0.1:8000', method='GET', uri='/javascripts/MathJax-2.7.5/extensions/MathMenu.js', version='HTTP/1.1', remote_ip='127.0.0.1', headers={'Host': '127.0.0.1:8000', 'Connection': 'keep-alive', 'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36', 'Dnt': '1', 'Accept': '*/*', 'Referer': 'http://127.0.0.1:8000/', 'Accept-Encoding': 'gzip, deflate, br', 'Accept-Language': 'fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7'})
    Traceback (most recent call last):
      File "/Users/victor/.pyenv/versions/3.6.4/lib/python3.6/site-packages/tornado/web.py", line 1512, in _execute
        result = yield result
      File "/Users/victor/.pyenv/versions/3.6.4/lib/python3.6/site-packages/tornado/gen.py", line 1055, in run
        value = future.result()
      File "/Users/victor/.pyenv/versions/3.6.4/lib/python3.6/site-packages/tornado/concurrent.py", line 238, in result
        raise_exc_info(self._exc_info)
      File "<string>", line 4, in raise_exc_info
      File "/Users/victor/.pyenv/versions/3.6.4/lib/python3.6/site-packages/tornado/gen.py", line 307, in wrapper
        yielded = next(result)
      File "/Users/victor/.pyenv/versions/3.6.4/lib/python3.6/site-packages/tornado/web.py", line 2422, in get
        yield self.flush()
      File "/Users/victor/.pyenv/versions/3.6.4/lib/python3.6/site-packages/tornado/web.py", line 947, in flush
        start_line, self._headers, chunk, callback=callback)
      File "/Users/victor/.pyenv/versions/3.6.4/lib/python3.6/site-packages/tornado/http1connection.py", line 400, in write_headers
        data += self._format_chunk(chunk)
      File "/Users/victor/.pyenv/versions/3.6.4/lib/python3.6/site-packages/tornado/http1connection.py", line 412, in _format_chunk
        "Tried to write more data than Content-Length")
    tornado.httputil.HTTPOutputError: Tried to write more data than Content-Length
[E 181003 11:32:04 web:1016] Cannot send error response after headers written

These 2 errors occur repeatedly until I stop the server.

Using --no-livereload prevents the issue, the server returns:

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /var/folders/qw/6ccdf6w14k354611cpl0x99h0000gn/T/tmpqlulnc9t
INFO    -  Running at: http://127.0.0.1:8000/
INFO    -  Hold ctrl+c to quit.

But the math don't render:

$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$

`--no-livereload` causes MkDocs to use a different server which probably handles the same error in a different way. You say the math doesn't render. Why not? What errors are reported by your browser? — Waylan, Oct 04 '18 at 23:06
I found [this bug report](https://github.com/lepture/python-livereload/issues/174) which may be relevant. Unfortunately there is not enough information to know for sure. And I'm not sure if that is a bug in Livereload or Tornado. If a bug in Tornado, then it would effect both of the servers. — Waylan, Oct 04 '18 at 23:09
Sorry, I'm out of ideas. I would suggest reaching out to the developer of `pymdownx.arithmatex`. I know that he uses the extension with MkDocs and he would likely be in a better position to help. — Waylan, Oct 05 '18 at 14:13

score 1 · Answer 1 · answered Dec 12 '18 at 16:44

Solution: Use a single file bundled MathJax instead.

For your case, I've seen the math render with this bundled. Working example

I thought this'd be easy, just either (a) modify mkdocs static server setting or (b) just bundle Mathjax altogether into 1 single .js file, webpack style.

For option (a), mkdocs doesn't provide that much customization for its static server...

Then I spent a long time on (b). Mathjax makes ajax call to load its extensions and file on its own, so it's incredibly difficult to bundle the whole thing together.

Just as I was about to try serving Mathjax statically on another local server, I found this article in Mathjax wiki, checkout the repo, load up one of the dist file and boom, it just works. Be sure to go over to that repo and give it a star!

Here's a working example with your string. The mathjax bundle is pretty large (1.9mb) so it'll take a while to load.

Local mathjax with mkdocs

1 Answers1

Linked