自定义您的主题

调整主题以满足您的需求。

如果您想对现有主题进行一些微调，无需从头开始创建自己的主题。对于仅需要一些 CSS 和/或 JavaScript 的轻微调整，您可以使用 docs_dir。然而，对于更复杂的自定义，包括覆盖模板，您需要使用 theme custom_dir 设置。

使用 docs_dir

extra_css 和 extra_javascript 配置选项可用于对现有主题进行调整和自定义。要使用这些选项，您只需在 [文档目录] 中包含 CSS 或 JavaScript 文件。

例如，要更改文档中标题的颜色，请创建一个名为（例如）style.css 的文件，并将其放在文档 Markdown 旁边。在该文件中添加以下 CSS。

h1 {
  color: red;
}

然后，您需要将其添加到 mkdocs.yml 中：

extra_css:
  - style.css

进行这些更改后，当您运行 mkdocs serve 时，应该可以看到这些更改 - 如果您已经运行了此命令，您应该会看到 CSS 更改被自动检测到，并且文档将被更新。

注意： 任何额外的 CSS 或 JavaScript 文件都将在生成的 HTML 文档的页面内容之后添加。如果您希望包含一个 JavaScript 库，通过使用主题 custom_dir 来包含该库可能会更成功。

使用 theme custom_dir

theme.custom_dir 配置选项可用于指向一个目录，该目录中的文件覆盖父主题中的文件。父主题将是在 theme.name 配置选项中定义的主题。custom_dir 中与父主题中同名的任何文件将替换父主题中同名的文件。custom_dir 中的任何额外文件将添加到父主题中。custom_dir 的内容应反映父主题的目录结构。您可以包含模板、JavaScript 文件、CSS 文件、图像、字体或主题中包含的任何其他媒体。

注意： 要使其工作，theme.name 设置必须设置为已安装的已知主题。如果 name 设置设置为 null（或未定义），则没有要覆盖的主题，custom_dir 的内容必须是完整的独立主题。有关更多信息，请参阅 主题开发者指南。

例如，mkdocs 主题（[浏览源代码]）包含以下目录结构（部分）：

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

要覆盖该主题中的任何文件，请在 docs_dir 旁边创建一个新目录：

mkdir custom_theme

然后，将您的 mkdocs.yml 配置文件指向新目录：

theme:
  name: mkdocs
  custom_dir: custom_theme/

要覆盖 404 错误页面（“文件未找到”），请在 custom_theme 目录中添加一个名为 404.html 的新模板文件。有关可以在模板中包含的内容的信息，请查看 主题开发者指南。

要覆盖 favicon，您可以在 custom_theme/img/favicon.ico 处添加一个新的图标文件。

要包含一个 JavaScript 库，请将该库复制到 custom_theme/js/ 目录中。

您的目录结构现在应如下所示：

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

注意： 父主题（在 name 中定义）中包含但未包含在 custom_dir 中的任何文件仍将被使用。custom_dir 只会覆盖/替换父主题中的文件。如果您想删除文件或从头开始构建主题，则应查看 主题开发者指南。

覆盖模板块

内置主题在其模板块内实现了许多部分，这些部分可以在 main.html 模板中单独覆盖。只需在 custom_dir 中创建一个 main.html 模板文件，并在该文件中定义替换块。只需确保 main.html 扩展了 base.html。例如，要更改 MkDocs 主题的标题，您的替换 main.html 模板将包含以下内容：

{% extends "base.html" %}

{% block htmltitle %}
<title>自定义标题在此</title>
{% endblock %}

在上面的示例中，在您的自定义 main.html 文件中定义的 htmltitle 块将用于替换父主题中定义的默认 htmltitle 块。您可以根据需要在父主题中定义的块重新定义任意数量的块。例如，您可以用不同服务的脚本替换 Google Analytics 脚本，或者用您的搜索功能替换默认的搜索功能。 own。你需要参考你正在使用的父主题，以确定哪些块可以被覆盖。MkDocs 和 ReadTheDocs 主题提供了以下块：

  • site_meta：包含文档头部的元标签。
  • htmltitle：包含文档头部的页面标题。
  • styles：包含样式表的链接标签。
  • libs：包含页面头部引入的 JavaScript 库（如 jQuery 等）。
  • scripts：包含应在页面加载后执行的 JavaScript 脚本。
  • analytics：包含分析脚本。
  • extrahead：在 <head> 中的一个空块，用于插入自定义标签/脚本等。
  • site_name：包含导航栏中的站点名称。
  • site_nav：包含导航栏中的站点导航。
  • search_button：包含导航栏中的搜索框。
  • next_prev：包含导航栏中的下一页和上一页按钮。
  • repo：包含导航栏中的仓库链接。
  • content：包含页面内容和页面的目录。
  • footer：包含页面页脚。

你可能需要查看源模板文件，以确保你的修改与站点的结构兼容。请参阅 [模板变量] 获取你可以在自定义块中使用的变量列表。有关块的更完整解释，请参阅 [Jinja 文档]。

结合 custom_dir 和模板块

将 JavaScript 库添加到 custom_dir 中会使其可用，但不会将其包含在 MkDocs 生成的页面中。因此，需要从 HTML 中添加对该库的链接。

从上述目录结构开始（截断）：

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

需要将 custom_theme/js/somelib.js 文件的链接添加到模板中。由于 somelib.js 是一个 JavaScript 库，它逻辑上应该放在 libs 块中。然而，仅包含新脚本的 libs 块将替换父模板中定义的块，并且父模板中对库的任何链接都将被移除。为了避免破坏模板，可以使用 super block，并在块内调用 super：

{% extends "base.html" %}

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

请注意，使用了 base_url 模板变量来确保链接始终相对于当前页面。

现在生成的页面将包含对模板提供的库以及 custom_dir 中包含的库的链接。对于 custom_dir 中包含的任何其他 CSS 文件，也需要进行同样的操作。