mkdocs学习笔记

完整官方文档： mkdocs.org.

安装¶

# 1. 安装 python
# 2. 安装 pip
# pip换源，此处为腾讯源
pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple

# 安装mkdocs
pip install mkdocs

# 安装主题
pip install mkdocs-material

# 插件
pip install mkdocs-minify-plugin

命令¶

• mkdocs new [dir-name] - 创建一个项目
• mkdocs serve - 启动服务
• mkdocs build - 构建静态文件
• mkdocs -h - 打印帮助文件

项目文件布局¶

新建项目后，会自动创建mkdocs.yml和 docs 目录，

mkdocs.yml    # 配置文件
docs/
    index.md  # 文档主页
    ...       # 其它文档文件

常用主题¶

1. GitBook Theme¶

安装：

pip install mkdocs-gitbook

使用，修改配置文件mkdocs.yml

theme: gitbook

2. mkdocs-material¶

配置指南：

• https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/
• https://wdk-docs.github.io/mkdocs-material-docs/setup/changing-the-fonts/

pip install mkdocs-material

theme:
  name: material

定制文档的导航栏¶

1. 手写所有的导航¶

在 mkdocs.yml 文件中写入以下配置

nav:
  - "index.md"
  - 标题名:
      - 标题名: "开发笔记/测试.md"
  - "about/about.md"

2. 使用插件自动生成导航¶

• 1.mkdocs-awesome-nav

  项目: https://github.com/lukasgeiter/mkdocs-awesome-nav

  文档：https://lukasgeiter.github.io/mkdocs-awesome-nav/ 用于自动生成Nav结构，不用再自己手写每个Nav了

安装

pip install mkdocs-awesome-nav

plugins:
   - search
   - awesome-nav

在docs目录下新建.nav.yml文件,写入

nav:
  - "*"

就可以自动根据docs文件目录，自动生成导航页了

• 2.

mkdocs 插件库及其常用推荐¶

MkDocs-Plugins：https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins catalog: https://github.com/mkdocs/catalog

常见问题报错¶

mkdocs编译报错jinja2.exceptions.TemplateNotFound: .icons/laptop-code.svg¶

最近使用 mkdocs，想用插件自动生成 Nav 导航，比如Awesome Nav，发现一直报这个错误

后面发现从vuepress转移过来的时候，markdown文件开头的metadata那部分，我自己标记了....

icon: laptop-code

或者其它解决：

1. 卸载 jinja2(pip uninstall jinja2)，重装最新版(pip install jinja2)
2. 去下载 laptop-code，放在overrides下的.icons/laptop-code.svg。

附录: 使用 mkdocs 的项目¶

• AWS Copilot CLI
• Google Accompanist
• MicroSoft Code With Engineering Playbook
• Mozilla Foundation Engineering Handbook
• Netflix Titus
• CentOS Infra docs
• electron-builder
• Kubernetes

评论