mkdocs是一个静态网页生成工具，可用于写博客或者教程，非常易于使用。在使用过程中，会发现有时会非常缓慢，经过本人的研究，找到了原因及其解决办法。
- 一 基本使用
- 二 缓慢的原因
- 三 解决办法
- 四 重新运行
一 基本使用
首先是安装mkdocs，
pip install mkdocs
然后创建工程，
mkdocs new my-project cd my-project
最后是运行，
mkdocs serve
当我们需要部署或者仅仅想生成本地的网页来查看时，使用下面命令，
mkdocs build
这个会在当前目录下生成site目录，里面是转换之后的网页文件。
二 缓慢的原因
打开site目录下的index.html，可以发现有2个文件是需要联网下载的，
如果使用了readthedocs主题，那么还会去使用谷歌的在线字体，
以上这些在国内有时候很难打开，特别是谷歌的在线字体，这就造成运行时非常缓慢。
三 解决办法
知道了原因，如何解决呢？因为网页是mkdocs自动生成的，本人经过思索，找到了一个好办法，就是对主题进行自定义。
mkdocs官方也给了说明 — https://www.mkdocs.org/user-guide/customizing-your-theme/
这里以readthedocs主题为例，首先在工程目录下创建新目录custom_theme，然后拷贝这个主题相关的文件到这个目录下，主题相关的文件在哪里呢？有2个办法：
-
在python的库安装目录里查找，即site-packages目录，如下这个目录里，就是主题相关的文件，
如果不知道site-packages目录在哪，可以使用以下的python语句去查看，import sys print(sys.path)
-
去github上下载mkdocs源码目录，然后在里面查找
原理同上，不再赘述
拷贝到custom_theme后，如下，
使用notepad++打开base.html，这个是网页模板，首先修改前面2个，一个是字体，一个是github.min.css，
字体这句改成如下，这个字体在主题文件里已经存在了。
然后修改第26行，
github.min.css可以去网上下载，或者拷贝如下内容，
.hljs{display:block;overflow-x:auto;padding:.5em;color:#333;background:#f8f8f8}.hljs-comment,.hljs-quote{color:#998;font-style:italic}.hljs-keyword,.hljs-selector-tag,.hljs-subst{color:#333;font-weight:700}.hljs-literal,.hljs-number,.hljs-tag .hljs-attr,.hljs-template-variable,.hljs-variable{color:teal}.hljs-doctag,.hljs-string{color:#d14}.hljs-section,.hljs-selector-id,.hljs-title{color:#900;font-weight:700}.hljs-subst{font-weight:400}.hljs-class .hljs-title,.hljs-type{color:#458;font-weight:700}.hljs-attribute,.hljs-name,.hljs-tag{color:navy;font-weight:400}.hljs-link,.hljs-regexp{color:#009926}.hljs-bullet,.hljs-symbol{color:#990073}.hljs-built_in,.hljs-builtin-name{color:#0086b3}.hljs-meta{color:#999;font-weight:700}.hljs-deletion{background:#fdd}.hljs-addition{background:#dfd}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}
最后保存到github.min.css里，然后把这个文件放到css目录里，
最后就是highlight.min.js，
同样去网上下载，最后放到js目录下，
四 重新运行
运行前，需要修改一下工程的配置文件mkdocs.yml，修改为如下，
site_name: My Docs
use_directory_urls: false
theme:
name: readthedocs
custom_dir: custom_theme/
PS：第2行可以根据需要决定是否使用，如果只是生成本地web文件，不需要部署，那就设置为false
输入已下命令重新build，
mkdocs build -c
如下，
此时再去使用浏览器打开site目录下的index.html，就会发现不再卡顿了。
