自定义¶

项目文档的多样性与项目本身一样丰富，而 Material for MkDocs 是使其看起来美观的绝佳起点。然而，在撰写文档时，您可能会遇到需要进行小调整以保持品牌风格的情况。

添加资源¶

MkDocs 提供了多种自定义主题的方式。为了对 Material for MkDocs 进行一些小调整，您只需将 CSS 和 JavaScript 文件添加到 docs 目录中。

附加 CSS¶

如果您想调整某些颜色或更改某些元素的间距，可以在单独的样式表中进行。最简单的方法是在 docs 目录中创建一个新的样式表文件：

.
├─ docs/
│  └─ stylesheets/
│     └─ extra.css
└─ mkdocs.yml

然后，将以下行添加到 mkdocs.yml 中：

extra_css:
  - stylesheets/extra.css

附加 JavaScript¶

如果您想集成另一个语法高亮器或向主题添加一些自定义逻辑，请在 docs 目录中创建一个新的 JavaScript 文件：

.
├─ docs/
│  └─ javascripts/
│     └─ extra.js
└─ mkdocs.yml

然后，将以下行添加到 mkdocs.yml 中：

extra_javascript:
  - javascripts/extra.js

如何与第三方 JavaScript 库集成

您可能希望在浏览器完全加载页面后再运行 JavaScript 代码。这意味着需要安装一个回调函数，订阅由 Material for MkDocs 导出的 document$ 可观察对象上的事件。使用 document$ 可观察对象尤其重要，如果您使用即时加载，因为这不会导致浏览器中的页面刷新，但可观察对象上的订阅者将会收到通知。

document$.subscribe(function() {
  console.log("在这里初始化第三方库")
})

document$ 是一个 RxJS 可观察对象，您可以调用 subscribe() 方法任意次数来附加不同的功能。

扩展主题¶

如果您想更改 HTML 源代码（例如，添加或删除某些部分），可以扩展主题。MkDocs 支持主题扩展，这是一种轻松覆盖 Material for MkDocs 部分内容的方法，而无需从 git 分支。这确保您可以更轻松地更新到最新版本。

设置和主题结构¶

像往常一样在 mkdocs.yml 中启用 Material for MkDocs，并为 overrides 创建一个新文件夹，然后使用 custom_dir 设置进行引用：

theme:
  name: material
  custom_dir: overrides

主题扩展前提条件

由于 custom_dir 设置用于主题扩展过程，因此需要通过 pip 安装 Material for MkDocs，并在 mkdocs.yml 中使用 name 设置进行引用。在从 git 克隆时将无法正常工作。

overrides 目录中的结构必须与原始主题的目录结构相对应，因为 overrides 目录中的任何文件都将替换原始主题中同名的文件。此外，还可以将其他资源放入 overrides 目录中：

.
├─ .icons/                             # 打包的图标集
├─ assets/
│  ├─ images/                          # 图像和图标
│  ├─ javascripts/                     # JavaScript 文件
│  └─ stylesheets/                     # 样式表
├─ partials/
│  ├─ integrations/                    # 第三方集成
│  │  ├─ analytics/                    # 分析集成
│  │  └─ analytics.html                # 分析设置
│  ├─ languages/                       # 翻译语言
│  ├─ actions.html                     # 操作
│  ├─ alternate.html                   # 网站语言选择器
│  ├─ comments.html                    # 评论系统（默认为空）
│  ├─ consent.html                     # 同意
│  ├─ content.html                     # 页面内容
│  ├─ copyright.html                   # 版权和主题信息
│  ├─ feedback.html                    # 这个页面对您有帮助吗？
│  ├─ footer.html                      # 页脚栏
│  ├─ header.html                      # 头部栏
│  ├─ icons.html                       # 自定义图标
│  ├─ language.html                    # 翻译设置
│  ├─ logo.html                        # 头部和侧边栏的徽标
│  ├─ nav.html                         # 主导航
│  ├─ nav-item.html                    # 主导航项
│  ├─ pagination.html                  # 分页（用于博客）
│  ├─ palette.html                     # 颜色调色板切换
│  ├─ post.html                        # 博客文章摘要
│  ├─ progress.html                    # 进度指示器
│  ├─ search.html                      # 搜索界面
│  ├─ social.html                      # 社交链接
│  ├─ source.html                      # 存储库信息
│  ├─ source-file.html                 # 源文件信息
│  ├─ tabs.html                        # 标签导航
│  ├─ tabs-item.html                   # 标签导航项
│  ├─ tags.html                        # 标签
│  ├─ toc.html                         # 目录
│  ├─ toc-item.html                    # 目录项
│  └─ top.html                         # 返回顶部按钮
├─ 404.html                            # 404 错误页面
├─ base.html                           # 基本模板
├─ blog.html                           # 博客索引页面
├─ blog-archive.html                   # 博客归档索引页面
├─ blog-category.html                  # 博客分类索引页面
├─ blog-post.html                      # 博客文章页面
└─ main.html                           # 默认页面

覆盖部分¶

为了覆盖一个部分，我们可以用同名和同位置的文件替换它。在 overrides 目录中创建一个新的 footer.html 部分以替换原始的 footer.html 部分：

.
├─ overrides/
│  └─ partials/
│     └─ footer.html
└─ mkdocs.yml

MkDocs 现在将在渲染主题时使用新的部分。这可以对任何文件进行。

覆盖块推荐¶

除了覆盖部分，还可以覆盖（和扩展）模板块，这些块在模板内部定义并包装特定功能。为了设置块覆盖，请在 overrides 目录中创建一个 main.html 文件：

.
├─ overrides/
│  └─ main.html
└─ mkdocs.yml

然后，例如，要覆盖网站标题，请在 main.html 中添加以下行：

{% extends "base.html" %}

{% block htmltitle %}
  <title>Lorem ipsum dolor sit amet</title>
{% endblock %}

如果您打算添加内容到一个块，而不是完全用新内容替换它，请在块内使用 {{ super() }} 来包含原始块内容。这在向文档中添加第三方脚本时特别有用，例如：

{% extends "base.html" %}

{% block scripts %}
  <!-- 在这里添加需要先运行的脚本 -->
  {{ super() }}
  <!-- 在这里添加需要后运行的脚本 -->
{% endblock %}

主题提供了以下模板块：

块名称	目的
`analytics`	包装 Google Analytics 集成
`announce`	包装公告栏
`config`	包装 JavaScript 应用程序配置
`container`	包装主要内容容器
`content`	包装主要内容
`extrahead`	空块以添加自定义元标签
`fonts`	包装字体定义
`footer`	包装带有导航和版权的页脚
`header`	包装固定的头部栏
`hero`	包装英雄预告（如果可用）
`htmltitle`	包装 `<title>` 标签
`libs`	包装 JavaScript 库（头部）
`outdated`	包装版本警告
`scripts`	包装 JavaScript 应用程序（页脚）
`site_meta`	包装文档头中的元标签
`site_nav`	包装网站导航和目录
`styles`	包装样式表（也包括额外来源）
`tabs`	包装标签导航（如果可用）

主题开发¶

Material for MkDocs 基于 TypeScript、RxJS 和 SASS 构建，并使用精简的自定义构建过程将所有内容组合在一起。¹ 如果您想进行更根本的更改，可能需要直接在主题源代码中进行调整并重新编译。

环境设置¶

首先，克隆该存储库：

git clone https://github.com/squidfunk/mkdocs-material
cd mkdocs-material

接下来，创建一个新的 Python 虚拟环境并激活它：

python -m venv venv
source venv/bin/activate

确保 pip 始终在虚拟环境中运行

如果您将环境变量 PIP_REQUIRE_VIRTUALENV 设置为 true，pip 将拒绝在虚拟环境之外安装任何内容。忘记激活 venv 可能会非常麻烦，因为它会随着时间的推移在虚拟环境之外安装各种东西，可能导致进一步的错误。因此，您可能想将其添加到您的 .bashrc 或 .zshrc 中并重新启动您的 shell：

export PIP_REQUIRE_VIRTUALENV=true

然后，安装所有 Python 依赖项：

pip install -e ".[git, recommended, imaging]"
pip install nodeenv

此外，您需要在系统中安装 cairo 和 pngquant 库，如图像处理需求指南中所述。

最后，在 Python 虚拟环境中安装 Node.js LTS 版本并安装所有 Node.js 依赖项：

nodeenv -p -n lts
npm install

开发模式¶

使用以下命令启动监视器：

npm start

然后，在第二个终端窗口中，启动 MkDocs 实时预览服务器：

mkdocs serve --watch-theme

在浏览器中访问 localhost:8000，您应该会看到这份文档在您面前。

自动生成的文件

切勿在 material 目录中进行任何更改，因为该目录的内容是从 src 目录自动生成的，并将在构建主题时被覆盖。

构建主题¶

完成更改后，您可以通过调用以下命令构建主题：

npm run build # (1)!

虽然此命令将构建所有主题文件，但它将跳过 Material for MkDocs 自身文档中使用的覆盖，这些覆盖并未与主题一起分发。如果您分叉了主题并希望构建覆盖，例如，在提交更改的 PR 之前，请使用：
```
npm run build:all
```
这将花费更长时间，因为现在还会构建图标搜索索引、架构文件以及其他样式表和 JavaScript 文件。

这将触发所有样式表和 JavaScript 文件的生产级编译和压缩。命令退出后，编译后的文件位于 material 目录中。当运行 mkdocs build 时，您现在应该能看到对原始主题的更改。

在 7.0.0 之前，构建基于 Webpack，因此由于加载器和插件的不兼容，偶尔会出现构建失败。因此，我们决定用更精简的解决方案替换 Webpack，该解决方案现在基于 RxJS 作为应用程序本身。这使得修剪了超过 500 个依赖项（减少约 30%）。 ↩