定制

¥Customization

项目文档本身就千差万别，Material for MkDocs 是让文档看起来更美观的绝佳起点。然而，在编写文档的过程中，您可能需要进行一些细微的调整，以保持品牌的风格。

¥Project documentation is as diverse as the projects themselves and Material for MkDocs is a great starting point for making it look beautiful. However, as you write your documentation, you may reach a point where small adjustments are necessary to preserve your brand's style.

添加资产

¥Adding assets

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

¥MkDocs provides several ways to customize a theme. In order to make a few small tweaks to Material for MkDocs, you can just add CSS and JavaScript files to the docs directory.

附加 CSS

¥Additional CSS

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

¥If you want to tweak some colors or change the spacing of certain elements, you can do this in a separate style sheet. The easiest way is by creating a new style sheet file in the docs directory:

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

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

¥Then, add the following lines to mkdocs.yml:

extra_css:
  - stylesheets/extra.css

附加 JavaScript

¥Additional JavaScript

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

¥If you want to integrate another syntax highlighter or add some custom logic to your theme, create a new JavaScript file in the docs directory:

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

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

¥Then, add the following lines to mkdocs.yml:

extra_javascript:
  - javascripts/extra.js

How to integrate with third-party JavaScript libraries

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

¥It is likely that you will want to run your JavaScript code only once the page has been fully loaded by the browser. This means installing a callback function subscribing to events on the document$ observable exported by Material for MkDocs. Using the document$ observable is particularly important if you are using instant loading since it will not result in a page refresh in the browser - but subscribers on the observable will be notified.

document$.subscribe(function() {
  console.log("Initialize third-party libraries here")
})

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

¥document$ is an RxJS Observable and you can call the subscribe() method any number of times to attach different functionality.

扩展主题

¥Extending the theme

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

¥If you want to alter the HTML source (e.g. add or remove some parts), you can extend the theme. MkDocs supports theme extension, an easy way to override parts of Material for MkDocs without forking from git. This ensures that you can update to the latest version more easily.

设置和主题结构

¥Setup and theme structure

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

¥Enable Material for MkDocs as usual in mkdocs.yml, and create a new folder for overrides which you then reference using the custom_dir setting:

theme:
  name: material
  custom_dir: overrides

主题扩展先决条件

¥Theme extension prerequisites

由于主题扩展过程中使用了custom_dir设置，因此需要通过pip安装 Material for MkDocs，并在mkdocs.yml中使用name设置进行引用。从git克隆时，此功能不起作用。

¥As the custom_dir setting is used for the theme extension process, Material for MkDocs needs to be installed via pip and referenced with the name setting in mkdocs.yml. It will not work when cloning from git.

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

¥The structure in the overrides directory must mirror the directory structure of the original theme, as any file in the overrides directory will replace the file with the same name which is part of the original theme. Besides, further assets may also be put in the overrides directory:

.
├─ .icons/                             # Bundled icon sets
├─ assets/
│  ├─ images/                          # Images and icons
│  ├─ javascripts/                     # JavaScript files
│  └─ stylesheets/                     # Style sheets
├─ partials/
│  ├─ integrations/                    # Third-party integrations
│  │  ├─ analytics/                    # Analytics integrations
│  │  └─ analytics.html                # Analytics setup
│  ├─ languages/                       # Translation languages
│  ├─ actions.html                     # Actions
│  ├─ alternate.html                   # Site language selector
│  ├─ comments.html                    # Comment system (empty by default)
│  ├─ consent.html                     # Consent
│  ├─ content.html                     # Page content
│  ├─ copyright.html                   # Copyright and theme information
│  ├─ feedback.html                    # Was this page helpful?
│  ├─ footer.html                      # Footer bar
│  ├─ header.html                      # Header bar
│  ├─ icons.html                       # Custom icons
│  ├─ language.html                    # Translation setup
│  ├─ logo.html                        # Logo in header and sidebar
│  ├─ nav.html                         # Main navigation
│  ├─ nav-item.html                    # Main navigation item
│  ├─ pagination.html                  # Pagination (used for blog)
│  ├─ palette.html                     # Color palette toggle
│  ├─ post.html                        # Blog post excerpt
│  ├─ progress.html                    # Progress indicator
│  ├─ search.html                      # Search interface
│  ├─ social.html                      # Social links
│  ├─ source.html                      # Repository information
│  ├─ source-file.html                 # Source file information
│  ├─ tabs.html                        # Tabs navigation
│  ├─ tabs-item.html                   # Tabs navigation item
│  ├─ tags.html                        # Tags
│  ├─ toc.html                         # Table of contents
│  ├─ toc-item.html                    # Table of contents item
│  └─ top.html                         # Back-to-top button
├─ 404.html                            # 404 error page
├─ base.html                           # Base template
├─ blog.html                           # Blog index page
├─ blog-archive.html                   # Blog archive index page
├─ blog-category.html                  # Blog category index page
├─ blog-post.html                      # Blog post page
└─ main.html                           # Default page

覆盖部分

¥Overriding partials

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

¥In order to override a partial, we can replace it with a file of the same name and location in the overrides directory. For example, to replace the original footer.html partial, create a new footer.html partial in the overrides directory:

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

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

¥MkDocs will now use the new partial when rendering the theme. This can be done with any file.

建议覆盖块

¥Overriding blocks recommended

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

¥Besides overriding partials, it's also possible to override (and extend) template blocks, which are defined inside the templates and wrap specific features. In order to set up block overrides, create a main.html file inside the overrides directory:

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

然后，例如要覆盖站点标题，请将以下几行添加到main.html中：

¥Then, e.g. to override the site title, add the following lines to main.html:

{% extends "base.html" %}

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

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

¥If you intend to add something to a block rather than to replace it altogether with new content, use {{ super() }} inside the block to include the original block content. This is particularly useful when adding third-party scripts to your docs, e.g.

{% extends "base.html" %}

{% block scripts %}
  <!-- Add scripts that need to run before here -->
  {{ super() }}
  <!-- Add scripts that need to run afterwards here -->
{% endblock %}

主题提供了以下模板块：

¥The following template blocks are provided by the theme:

块名称 ¥Block name	目的 ¥Purpose
analytics ¥analytics	包含 Google Analytics 集成 ¥Wraps the Google Analytics integration
announce ¥announce	包裹公告栏 ¥Wraps the announcement bar
config ¥config	包装 JavaScript 应用程序配置 ¥Wraps the JavaScript application config
container ¥container	包裹主要内容容器 ¥Wraps the main content container
content ¥content	包裹主要内容 ¥Wraps the main content
extrahead ¥extrahead	用于添加自定义元标记的空白块 ¥Empty block to add custom meta tags
fonts ¥fonts	包装字体定义 ¥Wraps the font definitions
footer ¥footer	用导航和版权信息包裹页脚 ¥Wraps the footer with navigation and copyright
header ¥header	包裹固定标题栏 ¥Wraps the fixed header bar
hero ¥hero	包装英雄预告片（如果有） ¥Wraps the hero teaser (if available)
htmltitle ¥htmltitle	包裹<title>标签 ¥Wraps the <title> tag
libs ¥libs	包装 JavaScript 库（标头） ¥Wraps the JavaScript libraries (header)
outdated ¥outdated	包装版本警告 ¥Wraps the version warning
scripts ¥scripts	包装 JavaScript 应用程序（页脚） ¥Wraps the JavaScript application (footer)
site_meta ¥site_meta	将元标记包裹在文档头中 ¥Wraps the meta tags in the document head
site_nav ¥site_nav	包含网站导航和目录 ¥Wraps the site navigation and table of contents
styles ¥styles	包装样式表（也包括额外的来源） ¥Wraps the style sheets (also extra sources)
tabs ¥tabs	包装标签导航（如果可用） ¥Wraps the tabs navigation (if available)

主题开发

¥Theme development

MkDocs 的 Material 建立在TypeScript 、 RxJS和SASS之上，并使用精益、自定义的构建流程将所有内容整合在一起。1如果您想进行更根本的更改，可能需要直接在主题源中进行调整并重新编译它。

¥Material for MkDocs is built on top of TypeScript, RxJS and SASS, and uses a lean, custom build process to put everything together.¹ If you want to make more fundamental changes, it may be necessary to make the adjustments directly in the source of the theme and recompile it.

环境设置

¥Environment setup

首先，克隆您想要处理的版本的仓库。如果您想克隆 Insiders 仓库，则需要先成为发起人才能获得访问权限。

¥First, clone the repository for the edition you want to work on. If you want to clone the Insiders repository, you need to become a sponsor first to gain access.

Material for MkDocsInsiders

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

您将需要拥有Insiders 文档中所述的GitHub 访问令牌，并将其在$GH_TOKEN变量中提供。

¥You will need to have a GitHub access token as described in the Insiders documentation and make it available in the $GH_TOKEN variable.

git clone https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git # (1)!

1. 如果您使用 SSH 密钥通过 GitHub 进行身份验证，则可以使用以下命令克隆 Insiders：

   git clone git@github.com:squidfunk/mkdocs-material-insiders.git
   

   git clone git@github.com:squidfunk/mkdocs-material-insiders.git
   

   git clone git@github.com:squidfunk/mkdocs-material-insiders.git git clone git@github.com:squidfunk/mkdocs-material-insiders.git

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

¥If you are using SSH keys for authenticating with GitHub, you can clone Insiders with this command:

python -m venv venv
source venv/bin/activate

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

¥Next, create a new Python virtual environment and activate it:

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

¥Ensure pip always runs in a virtual environment

export PIP_REQUIRE_VIRTUALENV=true

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

¥If you set the environment variable PIP_REQUIRE_VIRTUALENV to true, pip will refuse to install anything outside a virtual environment. Forgetting to activate a venv can be very annoying as it will install all sorts of things outside virtual environments over time, possibly leading to further errors. So, you may want to add this to your .bashrc or .zshrc and re-start your shell:

Material for MkDocsInsiders

pip install -e ".[recommended]"
pip install nodeenv

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

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

¥Then, install all Python dependencies:

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

¥In addition, you will need to install the cairo and pngquant libraries in your system, as described in the image processing requirements guide.

nodeenv -p -n lts
npm install

开发模式

¥Development mode

使用以下命令启动观察器：

¥Finally, install the Node.js LTS version into the Python virtual environment and install all Node.js dependencies:

npm start

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

¥Start the watcher with:

mkdocs serve --watch-theme

将您的浏览器指向localhost:8000 ，您应该会看到您面前的这个文档。

¥Then, in a second terminal window, start the MkDocs live preview server with:

自动生成的文件

¥Point your browser to localhost:8000 and you should see this very documentation in front of you.

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

¥Automatically generated files

构建主题

¥Building the theme

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

¥Never make any changes in the material directory, as the contents of this directory are automatically generated from the src directory and will be overwritten when the theme is built.

npm run build # (1)!

1. 虽然此命令将构建所有主题文件，但它将跳过 Material 中用于 MkDocs 自身文档的覆盖，这些覆盖未随主题分发。如果您分叉了主题并希望构建覆盖，例如在提交包含更改的 PR 之前，请使用：

   npm run build:all
   

   npm run build:all
   

   npm run build:all npm run build:all这将花费更长的时间，因为现在构建了图标搜索索引、模式文件以及附加样式表和 JavaScript 文件。

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

¥When you're finished making your changes, you can build the theme by invoking:

---

1. 在7.0.0之前的版本中，构建是基于 Webpack 的，由于加载器和插件不兼容，偶尔会导致构建失败。因此，我们决定将 Webpack 替换为更精简的解决方案，该解决方案现在基于RxJS作为应用程序本身。这让我们能够精简 500 多个依赖项（减少了约 30%）。 ↩