配置文件解析¶
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_dir
和site_dir
设置
theme¶
MkDocs
提供了mkdocs
和readthedocs
,还可以使用第三方插件,比如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
是配置文件中最重要的属性之一,通过它实现章节目录的设置
如果没有设置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
个子章节