mkdocs

MkDocs 是一个静态站点生成器，和 Hexo 类似，但风格比 Hexo 简约，常常可以看到使用 MkDocs 搭建的博客、 项目文档等。

📄文档

安装

pip install mkdocs

使用 mkdocs -V 检查安装是否成功

创建项目

mkdocs new my-project

初始化项目后，我们得到一个配置文件 mkdocs.yml，一个文件夹 docs

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

我们可以把文档和静态资源都放在 docs 文件夹下，再通过编辑配置文件 mkdocs.yml 来使得站点整齐地呈现内容。

启动服务

mkdocs serve

添加页面

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

设置导航

# mkdocs.yml
nav:
  - 导航名称1: doc1.md
  - 导航名称2: doc2.md

导航可以设置为多级

# mkdocs.yml
nav:
  - [一级目录名称]:
    - [子目录名称]:[文件路径/文件名.md]
    ...

其中 [子目录名称] 可以省略，如果省略，那么当前页面名称即显示为该 markdown 文件的一级标题。

构建站点

mkdocs build

该命令会在项目根目录下生成站点文件。

启用 latex

安装插件

pip install python-markdown-math

编辑配置文件

# mkdocs.yml
extra_javascript:
  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js?config=TeX-AMS-MML_HTMLorMML
markdown_extensions:
  - mdx_math

attr_list

此插件用于修改 html 标签元素

📄 👉 https://python-markdown.github.io/extensions/attr_list/

编辑配置文件

markdown_extensions:
  - attr_list

pymdown-extensions

admonition

References

[1] MkDocs 文档开发教程
[2] MkDocs
[3] josemazo, LaTeX within MkDocs
[4] PyMdown Extensions Documentation
[5] 问我学院, Mkdocs 配置和使用