配置文件解析

MkDocs工程的所有配置仅使用mkdocs.yml完成，新建工程得到的配置文件仅设置了网站名属性

$ cat mkdocs.yml 
site_name: My Docs

详细的配置参考官网教程Configuration

下面首先展示当前使用的配置，然后讲解相关的配置选项

完整配置

# 站点名称
site_name: 'DocGuide'
# 仓库链接
repo_url: https://github.com/ZJDoc/DocGuide.git
# 作者
site_author: 'zhujian'
# 版权信息
copyright: '2021, zhujian'
# 源文件目录
docs_dir: 'docs'
# 生成静态文件目录
site_dir: 'site'
# 额外信息
extra:
    # 版本号
    version: 0.1.0
# 主题
theme: 
    # name: 'readthedocs'
    # name: 'mkdocs'
    name: 'material'
# markdown扩展
markdown_extensions:
  # 参考[MathJax](https://squidfunk.github.io/mkdocs-material/reference/mathjax/)，支持数学公式渲染
  - pymdownx.arithmatex:
      generic: true
    # 参考[Icons + Emojis](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/)，执行Markdown Emoji
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg

# mathjax
extra_javascript:
  - javascripts/config.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

# 导航
nav:
    - Home: index.md
    - Markdown:

repo_url

指定仓库链接后，有的主题会在右上角显示相应的图标

docs_dir & site_dir

默认使用docs作为源文件目录，site作为静态文件目录，可通过属性docs_dir和site_dir设置

theme

MkDocs提供了mkdocs和readthedocs，还可以使用第三方插件，比如mkdocs-material

# 安装
pip install mkdocs-material
# 配置
theme:
  name: 'material'

markdown_extensions

扩展功能，具体参考后续章节

nav

属性nav是配置文件中最重要的属性之一，通过它实现章节目录的设置

如果没有设置nav属性，那么网站菜单栏会显示docs文件夹内的所有文件，当使用nav指定了要显示的文件后，其他文件会被编译，但是不会出现在网页菜单栏上

最简单的设置

nav:
    - 'index.md'
    - 'about.md'

当前仅在菜单栏上显示index.md和about.md两文件

高级设置

可以指定文件的同时设置菜单栏显示名

nav:
    - Home: 'index.md'
    - About: 'about.md'

嵌套显示如下：

nav:
    - Home: index.md
    - User Guide:
        - 'Writing your docs': writing-your-docs.md
        - 'Styling your docs': styling-your-docs.md
    - About:
        - License: license.md
        - 'Release Notes': release-notes.md

在菜单栏有3个选项，分别显示Home/User Guide/About，其中User Guide存在子标题Writing your docs和Styling your docs，About同样存在2个子章节