Sphinx加载HTML页面过慢元凶之MathJax.js

这几天偶然发现用Sphinx reST生成的HTML页面加载异常缓慢,经排查,原来是我不小心在配置中启用了MathJax,加载了一个外部JS文件所导致。

在使用sphinx-quickstart命令创建Project的过程中,有一系列的Y/N配置选项供选择。默认情况下,我习惯都选择Y(表示Yes)。问题就出在这里,有些你没用到的配置项,不去细看的话,就不会发现它们到底会产生何种影响。请看下面这张图:

sphinx-create-options

如果我继续按下Y键并回车,默认就会启用MathJax。这玩意会在生成的HTML页面中加载一个外部JS文件,地址是:

http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML

如果这个JS文件访问有问题,就会严重影响网页加载的速度。之前我没有发现这个问题,估计是因为这个URL地址大部分时候连接都挺顺畅的。

解决方法呢,自然就出来了。可以选择在创建Proejct的时候不要启用MathJax;对于已经创建好的Project,则可以修改一下其配置文件conf.py,把extensions配置项中的sphinx.ext.mathjax删掉即可。

MathJax主要用于在网页上显示数学公式,我用不到这么高级的东西,所以直接禁用就好了。如果你需要在Sphinx中用到这个功能,建议使用加载本地JS的方式来规避这个潜在的问题。相关的操作可参考:

http://sphinx-doc.org/latest/ext/math.html

发表回复

您的电子邮箱地址不会被公开。 必填项已用 * 标注