自定义

项目文档与项目本身一样多样化，而 MkDocs Material 是使其外观美观的绝佳起点。然而，在编写文档时，您可能会遇到需要进行一些小调整以保留品牌风格的情况。

添加资源

MkDocs提供了几种自定义主题的方法。为了对 MkDocs Material 进行一些小的调整，您只需将 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

扩展主题

如果您想要修改 HTML 源代码（例如添加或删除某些部分），您可以扩展主题。MkDocs 支持主题扩展，这是一种在不从 git 分支中进行分叉的情况下覆盖 Material for MkDocs 的一部分的简单方法。这确保您可以更轻松地更新到最新版本。

设置和主题结构

像往常一样，在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                     # 操作
│  ├─ 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                  # 分页（用于博客）
│  ├─ post.html                        # 博客文章摘要
│  ├─ search.html                      # 搜索界面
│  ├─ social.html                      # 社交链接
│  ├─ source.html                      # 仓库信息
│  ├─ source-file.html                 # 源文件信息
│  ├─ tabs.html                        # 标签导航
│  ├─ tabs-item.html                   # 标签导航项
│  ├─ tags.html                        # 标签
│  ├─ toc.html                         # 目录
│  └─ toc-item.html                    # 目录项
├─ 404.html                            # 404错误页面
├─ base.html                           # 基本模板
├─ blog.html                           # 博客索引页面
├─ blog-archive.html                   # 博客归档索引页面
├─ blog-category.html                  # 博客分类索引页面
├─ blog-post.html                      # 博客文章页面
└─ main.html                           # 默认页面

覆盖部分

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

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

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

覆盖块推荐

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

.
├─ 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构建，并使用精简、定制的构建流程将所有内容整合在一起。¹如果您想进行更根本的更改，可能需要直接在主题源代码中进行调整并重新编译。

环境设置

为了开始 Material for MkDocs 的开发，需要至少 14 版本的Node.js。首先，克隆存储库：

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

接下来，需要安装所有依赖项：

cd mkdocs-material
pip install -e .
pip install mkdocs-minify-plugin
pip install mkdocs-redirects
npm install

开发模式

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

npm start

然后，在第二个终端窗口中，使用以下命令启动 MkDocs 实时预览服务器：

mkdocs serve --watch-theme

将浏览器指向localhost:8000，您应该能够看到此文档。

自动生成的文件

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

构建主题

完成更改后，可以通过运行以下命令构建主题：

npm run build # (1)!

虽然此命令将构建所有主题文件，但将跳过用于 Material for MkDocs 自身文档的覆盖文件，这些文件不随主题一起分发。如果您分叉了主题并且还想构建覆盖文件，请使用：

npm run build:all

这将需要更长时间，因为现在构建了图标搜索索引、模式文件以及其他样式表和 JavaScript 文件。

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

企业支持

如果您的组织正在使用Material for MkDocs，并且需要帮助，例如缩短构建时间、提高性能或确保合规性，请联系我们讨论我们的企业支持服务。我们乐意提供帮助！

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

自定义