Mkdocs配置教程

环境

• Windows 10
• Python

安装

需要预先安装过Python和pip，配置好Python的环境变量。

pip install mkdocs
mkdocs --version
# mkdocs, version 1.1.2 from c:\applications\anaconda3\lib\site-packages\mkdocs (Python 3.7)

创建项目

mkdocs new pocGuide
cd pocGuide

目录结构如下

.
├── docs
│   ├── index.md
└── mkdocs.yml

• mkdocs.yml：配置文件
• docs文件夹：包含我们的文档源文件。index.md是自动生成的文档页面。

在项目目录下，我们可以运行mkdocs serve命令来启动服务器：

mkdocs serve
# INFO    -  Building documentation...
# INFO    -  Cleaning site directory
# [I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
# [I 160402 15:50:43 handlers:58] Start watching changes
# [I 160402 15:50:43 handlers:60] Start detecting changes

在浏览器中打开http://127.0.0.1:8000/，就能看到默认的主页：

修改配置文件

用文本编辑器打开docs/index.md文件，将内容改为查阅手册，浏览器会自动重新加载更新后的文档。

更改配置文件mkdocs.yml，设置如下：

更新后的界面

添加页面

• 创建docs/about.md文件，并加入内容关于界面。
• 并为关于界面添加导航，在mkdocs.yml中修改为：
  
  更新后的界面：
  

生成网站

• 先生成文档

  mkdocs build
  

  这将创建一个名为site的新目录，该目录中的内容为

  ls site
  # about  fonts  index.html  license  search.html
  # css    img    js          mkdocs   sitemap.xml
  

  这里输出了index.html和about/index.html的HTML文件，

版本控制

cd pocGuide
git init
echo # pocGuide >> README.md
echo site/ >> .gitignore
git add README.md
git commit -m "first commit"
git remote add origin https://gitee.com/coasxu/pocGuide.git
git push -u origin master

部署到Gitee Pages上

mkdocs gh-deploy
# INFO    -  Cleaning site directory
# INFO    -  Building documentation to directory: C:\Users\11244\Desktop\Projects\pocGuide\site
# INFO    -  Documentation built in 0.20 seconds
# WARNING -  Version check skipped: No version specified in previous deployment.
# INFO    -  Copying 'C:\Users\11244\Desktop\Projects\pocGuide\site' to 'gh-pages' branch and pushing to GitHub.
# INFO    -  Your documentation should be available shortly.

打开Gitee上的项目主页，选择服务，Gitee Pages.

设置如下：

生成完毕后，可以通过 https://coasxu.gitee.io/pocguide/ 访问

使用数学公式

pip install pymdown-extensions

在mkdocs.yml中添加设置

# mkdocs.yml file

# other settings ...

markdown_extensions:
   # other extensions ...
   - pymdownx.arithmatex

# other settings ...

extra_javascript:
  # other extra java script
  - mathjax-config.js
  - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML

# other settings ...

mathjax-config.js设置MathJax
创建docs/mathjax-config.js文件，添加内容如下：

/* mathjax-loader.js  file */
/* ref: http://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/ */
(function (win, doc) {
  win.MathJax = {
    config: ["MMLorHTML.js"],
    extensions: ["tex2jax.js"],
    jax: ["input/TeX"],
    tex2jax: {
      inlineMath: [ ["\\(","\\)"] ],
      displayMath: [ ["\\[","\\]"] ]
    },
    TeX: {
      TagSide: "right",
      TagIndent: ".8em",
      MultLineWidth: "85%",
      equationNumbers: {
        autoNumber: "AMS",
      },
      unicode: {
        fonts: "STIXGeneral,'Arial Unicode MS'"
      }
    },
    displayAlign: 'center',
    showProcessingMessages: false,
    messageStyle: 'none'
  };
})(window, document);

参考：https://github.com/mkdocs/mkdocs/issues/253

可能有用的解答：

• https://squidfunk.github.io/mkdocs-material/reference/mathjax/
• https://stackoverflow.com/questions/27882261/mkdocs-and-mathjax

安装主题

pip install mkdocs-bootswatch

该主题似乎无法显示markdown的数学公式。

改用

pip install mkdocs-rtd-dropdown

更多的主题可以看：https://mkdocs-like-code.readthedocs.io/zh_CN/latest/MkDocs-advanced-operations/theme-configuration/

问题

1. mkdocs gh-deploy无效，本地版本与服务器端的版本冲突，使用mkdocs gh-deploy --force指令即可解决。

参考：

1. 使用mkdocs撰写技术文档并免费部署上线
2. MkDocs中文文档
3. Gitee Pages