Local mathjax with mkdocs

问题

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}
$$

回答1:

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.

来源：https://stackoverflow.com/questions/52624102/local-mathjax-with-mkdocs

标签

javascript

python

mathjax

mkdocs