定制MkDocs主题

对主题进行定制

根据你自己的需求修改主题

如果你想对已有的主题进行一些微调，那就没有必要使用脚手架从头创建一个新的主题，一些简单的调整例如添加一些额外的CSS/JS文件到现有主题，你可以参照下面的使用docs_dir 章节，如果你需要做一些更复杂深入的主题定制，你可以参考下面的使用 custom_dir 章节进行设置

使用 docs_dir

extra_css 和 extra_javascript 配置选项可以用来对已有的主题进行微调定制，使用这两个配置选项，你首先需要地将CSS/JS文件放在docs_dir目录下举例来说，假如你想要改变页面中的header的颜色，你可以创建一个style.css的文件并将它跟你的Markdown文件放在一个目录下，在style.css中你可以添加如下代码：

h1 {
  color: red;
}

然后在项目的 mkdocs.yml 里面添加：

extra_css:
  - style.css

做完上述改变后，你可以执行mkdocs serve 预览效果，如果mkdocs serve已经运行，你应该可以看到自定义CSS的效果已经自动应用到文档中了

注意：所有额外的CSS/JS文件都会被添加到生成的HTML文件内容的后面，如果你想在页面内引入一个JS库，最好参照下面的“使用 custom_dir 来引入整个JS库

使用 custom_dir

theme.custom_dir 配置参数指向的目录用来覆盖使用的主题中的文件，项目中使用的主题名称通过theme.name指定。custom_dir指定的目录中的文件将覆盖使用的主题中同名称的文件。custom_dir中新增的文件将添加到使用的主题中。custom_dir中的内容需要跟使用的主题保持相同的目录结构。你可以在custom_dir中放置模版文件、js文件、css文件、图像、字体或者其他媒体文件。

注意：如果你是想覆盖使用的主题，你需要通过 theme.name 来指定一个已经安装好的主题名称。如果 theme.name 未设置或者被设置为null，那么将无父主题课覆盖，那么 custom_dir 文件里面的内容必须构成一个完整独立的主题，可以查看Theme Developer Guide 浏览更多信息

举例来说，mkdocs 主题（源码地址）的部分目录结构如下：

- css\
- fonts\
- img\
  - favicon.ico
  - grid.png
- js\
- 404.html
- base.html
- content.html
- nav-sub.html
- nav.html
- toc.html

如果想覆盖该主题中的文件，在项目中跟docs_dir同级目录中创建custom_theme目录：

mkdir custom_theme

然后在mkdocs.yml中通过配置指向改目录：

theme:
  name: mkdocs
  custom_dir: custom_theme/

覆盖mkdocs中404错误页面时，在custom_theme中新增一个404.html文件即可，想了解页面模版的内容组成，可以查看Theme Developer Guide

其他文件覆盖方法类似，如果想覆盖 favicon，可以新增你自己的 custom_theme/img/favicon.ico 文件，想包含一个JS库，赋值JS库到 custom_theme/js/ 目录下即可

完成上述几个覆盖后，你的项目看起来是下面的结构：

- docs/
  - index.html
- custom_theme/
  - img/
    - favicon.ico
  - js/
    - somelib.js
  - 404.html
- config.yml

注意：主题中未被custom_dir中文件覆盖其他文件将会被继续使用，custom_dir只会对使用主题中的文件进行覆盖/替换，如果你想删除主题中的文件，或者从脚手架构建一个新主题，请浏览Theme Developer Guide

重写模版块

主题一般会在main.html模版文件中使用多段内置的模版块片段，这些模版块片段都能被独立重写。首先在custom_dir目录中创建一个main.html模版文件，然后在main.html中重写模版块。请注意main.html必须从base.html继承。举例来说，如果想改变 MkDocs 主题下页面的标题，你可以重写main.html模版文件为如下代码：

{% extends "base.html" %}

{% block htmltitle %}
<title>Custom title goes here</title>
{% endblock %}

在上述示例中，重写的htmltitle模版块将会替换原始主题中的htmltitle模版块，你可以重定义任意数量在使用主题中已经定义的模版块。举例来说，你可以使用一个其他的统计组件来替换主题中 Google Analytics 相关的模板块，或者使用你自己的搜索组件。因此你也需要知道你使用的主题有多少可替换的模板块，MkDocs 和 ReadTheDocs 主题使用了如下模板块：

site_meta: 页面 <head> 中的meta 标签模版块
htmltitle: <head> 中的页面标题
styles: 页面样式标签和连接
libs: 页面<head>中的JS库引用模版块
scripts: 页面加载后需要执行的脚本模版块
analytics: 页面分析脚本相关的模版块
extrahead: 默认是一个空内容的模版块，可用于在<head>标签中插入自定义的标签/脚本等代码
site_name: 导航条中的站点名称模版块
site_nav: 导航条中的站点导航模版块
search_button: 导航条中的搜索框模版块
next_prev: 导航条中的上一页下一页链接模版块
repo: 导航条中的仓库链接模版块
content: 页面内容和内容索引链接模版块
footer: 页面页脚部分的模版块

你可以查看原始的模版文件来确认你的修改在站点中是否生效，浏览Template Variables来查看你可以在模版块中可以使用的变量列表，关于模版块的更详细完整的说明，可查看Jinja documentation

custom_dir 和模版块结合使用

在custom_dir中添加一个js脚本文件，这个脚本文件会进入最终生成的站点内容中，但是并不会自动包含到 MkDocs 生成的页面中，如果需要这么做，你需要手动将指向该js脚本的链接添加到生成的HTML文件中。

例如，我们重新创建一个如下的目录结构的项目：

- docs/
- custom_theme/
  - js/
    - somelib.js
- config.yml

为了让 custom_theme下的 js/somelib.js文件进入页面，我们需要在模版文件中将 custom_theme/js/somelib.js 通过脚本链接引用进来。js库文件一般通过libs模版块中定义。但是需要注意的是：我们重写libs模版块的时候，使用主题中整个libs块将被覆写，这意味中主题中原来的代码都将被替换，如果我们只是想在使用主题中libs块中保留原来内容基础上引入新的内容，我们可以使用super block中提到的super 实现：

{% extends "base.html" %}

{% block libs %}
    {{ super() }}
    <script src="{{ base_url }}/js/somelib.js"></script>
{% endblock %}

注意：base_url模版变量表示的是相对于当前页面的路径。通过上述代码生成的页面将既包含使用主题中定义的libs块中的内容也将包含custom_dir目录下我们自定义的库文件。也可以使用同样的方式引入在custom_dir目录下的CSS等其他文件。