配置文件解析

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

$ cat mkdocs.yml 
site_name: My Docs

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

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

完整配置

# 站点名称
site_name: 'MkDocs-Github-Readthedocs'
# 仓库链接
repo_url: 
# 作者
site_author: 'zhujian'
# 版权信息
copyright: '2019, zhujian'
# 源文件目录
docs_dir: 'docs'
# 生成静态文件目录
site_dir: 'site'
# 额外信息
extra:
    # 版本号
    version: 1.0
# 主题
theme: 
    # name: 'readthedocs'
    # name: 'mkdocs'
    name: 'material'
# markdown扩展
markdown_extensions:
    - toc:
        permalink: true
    - pymdownx.arithmatex

extra_javascript:
    - 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML'
# 导航
nav:
    - Home: index.md
    - MkDocs:
        - 介绍: './mkdocs/引言.md'
        - Get-Started: './mkdocs/get-started.md'
        - 配置文件解析: './mkdocs/配置文件解析.md'
    - reStructuredText: 
        - 常用语法: 'reStructuredText/reStructuredText-常用语法.md'
        - 目录树: 'reStructuredText/Sphinx-目录树.md'    
    - Sphinx: 
        - 介绍: 'sphinx/Sphinx - 介绍.md'
        - 新建文档工程: 'sphinx/Sphinx - 新建文档工程.md'
        - html主题: 'sphinx/Sphinx - html主题.md'
        - markdown配置: 'sphinx/Sphinx - markdown配置.md'
        - MathJax配置: './sphinx/Sphinx - MathJax.md'
        - bug: 'sphinx/Sphinx - bug.md'
    - Pandoc: 'pandoc-文档转换工具.md'
    - Readthedocs: 
        - 介绍: './readthedocs/ReadtheDocs - 介绍.md'

repo_url

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

docs_dir & site_dir

默认使用docs作为源文件目录,site作为静态文件目录,可通过属性docs_dirsite_dir设置

theme

MkDocs提供了mkdocsreadthedocs,还可以使用第三方插件,比如mkdocs-material

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

markdown_extensions

当前设置了两个扩展功能,一是开启子章节链接,二是设置数学公式渲染(参考PyMdown Extensions

markdown_extensions:
    - toc:
        permalink: true
    - pymdownx.arithmatex

extra_javascript:
    - 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML'

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

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

最简单的设置:

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

当前仅在菜单栏上显示index.mdabout.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 docsStyling your docsAbout同样存在2个子章节