解决mkdocs运行缓慢的问题

解决mkdocs运行缓慢的问题

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个办法：

1. 在python的库安装目录里查找，即site-packages目录，如下这个目录里，就是主题相关的文件，
   
   如果不知道site-packages目录在哪，可以使用以下的python语句去查看，

   import sys
   print(sys.path)
   

2. 去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，就会发现不再卡顿了。