MkDocs 材料提供了多种自定义文档的选项。在本节中，我们将解释如何为您的网站创建有意义的结构、更改外观和感觉、添加博客和评论系统以及构建高度优化的网站。
颜色
颜色主题
MkDocs 的 Material 支持两种配色方案：浅色模式（简称 default）和深色模式（称为 slate）。颜色方案可以通过 mkdocs.yml 进行设置：
theme:
palette:
scheme: default
可选参数：default、slate
基本颜色
主要颜色用于标题、侧边栏、文本链接和其他几个组件。要更改主要颜色，请在 mkdocs.yml 中将以下值设置为有效的颜色名称：
theme:
palette:
primary: indigo
可选参数：red、pink、purple、deep purple、indigo、blue、light blue、cyan、teal、green、light green、lime、yellow、amber、orange、deep orange、brown、grey、blue grey、black、white
强调颜色
theme:
palette:
accent: indigo
red、pink、purple、deep purple、indigo、blue、light blue、cyan、teal、green、light green、lime、yellow、amber、orange、deep orange
调色板切换
提供浅色和深色调色板可使您的文档在一天中的不同时间阅读舒适，因此用户可以相应地进行选择。将以下行添加到 mkdocs.yml：
theme:
palette:
# Palette toggle for light mode
- scheme: default
toggle:
icon: material/brightness-7
name: Switch to dark mode
# Palette toggle for dark mode
- scheme: slate
toggle:
icon: material/brightness-4
name: Switch to light mode
此配置将在搜索栏旁边呈现调色板切换。请注意，您还可以为每个调色板定义 Primary 和 Accent 的单独设置。
字体
Material for MkDocs 可以轻松更改项目文档的字体，因为它直接与 Google Fonts 集成。或者，如果出于数据隐私原因首选自托管或应使用其他目标，则可以自定义加载字体。
常规字体
常规字体用于所有正文、标题以及基本上不需要等宽的所有内容。可以通过 mkdocs.yml 将其设置为任何有效的 Google 字体：.
theme:
font:
text: Roboto
等宽字体
等宽字体用于代码块，可以单独配置。就像常规字体一样，它可以通过 mkdocs.yml 设置为任何有效的 Google 字体：
theme:
font:
code: Roboto Mono
自动加载
如果要防止从 Google Fonts 加载字体，例如为了遵守数据隐私法规，并回退到系统字体，请在 mkdocs.yml中添加以下行：
theme:
font: false
语言
MkDocs 材料支持国际化 （i18n），并提供 60+ 种语言的模板变量和标签翻译。此外，还可以将站点搜索配置为使用特定于语言的词干分析器（如果可用）。
theme:
language: zh
可选参数：zh、en、ja、kn、ko、ru、gl
语言选择器
如果您的文档提供多种语言版本，则可以将指向这些语言的语言选择器添加到页眉中。可以通过 mkdocs.yml 定义替代语言。
extra:
alternate:
- name: English
link: /en/
lang: en
- name: 中文
link: /zh/
lang: zh
logo和icon
安装 Material for MkDocs 时，您可以立即访问 8,000 多个图标，这些图标可用于自定义主题的特定部分和/或在 Markdown 中编写文档。还不够？您还可以轻松添加其他图标。
logo
logo可以更改为位于 docs 文件夹中的用户提供的图像（任何类型，包括 *.png 和 *.svg），或更改为与主题捆绑的任何图标。将以下行添加到 mkdocs.yml：
theme:
logo: img/logo.png
通常，页眉和侧边栏中的 logo 会链接到文档的主页，这与 site_url 相同。可以通过以下配置更改此行为：
extra:
homepage: https://example.com
favicon
网站图标可以更改为指向用户提供的图像的路径，该图像必须位于 docs 文件夹中。将以下行添加到 mkdocs.yml：
theme:
favicon: img/favicon.png
站点icon
您在网站上看到的大多数图标（如导航图标）也可以更改。例如，要更改页脚中的导航箭头，请向 mkdocs.yml 添加以下行：
theme:
icon:
previous: fontawesome/solid/angle-left
next: fontawesome/solid/angle-right
确保数据隐私
Material for MkDocs 使遵守数据隐私法规变得非常容易，因为它提供了一个原生 cookie 同意解决方案，可以在设置分析之前征求用户的明确同意。此外，可以自动下载外部资产以进行自托管。
Cookie 同意
MkDocs 的材料提供了一个原生且可扩展的 cookie 同意书，该同意书在向第三方发送请求之前征求用户的同意。将以下内容添加到 mkdocs.yml：
extra:
consent:
title: Cookie consent
description: >-
We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.
设置导航
清晰简洁的导航结构是优秀项目文档的一个重要方面。Material for MkDocs 提供了多种选项来配置导航元素的行为，包括选项卡和部分，以及它的旗舰功能之一：即时加载。可以在 footer 中以及使用 tags 插件配置其他导航。博客插件还设置了其他导航。
即时加载
启用即时加载后，所有内部链接的点击都将被拦截并通过 XHR 调度，而无需完全重新加载页面。将以下行添加到 mkdocs.yml：
theme:
features:
- navigation.instant
生成的页面被解析和注入，所有事件处理程序和组件都会自动重新绑定，即 Material for MkDocs 现在的行为类似于单页应用程序。现在，搜索索引在导航后仍然存在，这对于大型文档站点特别有用。
必须设置 site_url
请注意，使用即时导航时必须设置site_url，因为即时导航依赖于生成的sitemap.xml，如果省略此设置，该将为空。例：
site_url: https://example.com
即时预取
即时预取是一项新的实验性功能，当用户将鼠标悬停在链接上时，它将开始获取页面。这将减少用户的感知加载时间，尤其是在连接速度较慢的情况下，因为页面将在导航后立即可用。使用以下方法启用它：
theme:
features:
- navigation.instant
- navigation.instant.prefetch
进度指示器
为了在使用即时导航时在慢速连接时提供更好的用户体验，可以启用进度指示器。它将显示在页面顶部，并在页面完全加载后隐藏。您可以在 mkdocs.yml 中使用以下命令启用它：
theme:
features:
- navigation.instant
- navigation.instant.progress
仅当页面在 400 毫秒后仍未完成加载时，才会显示进度指示器，因此快速连接永远不会显示它以获得更好的即时体验。
设置网站搜索
Material for MkDocs 提供了出色的客户端搜索实现，无需集成第三方服务，这可能不符合隐私法规。此外，搜索甚至可以离线工作，允许用户下载您的文档。
内置搜索插件
内置的搜索插件与 Material for MkDocs 无缝集成，使用 lunr 和 lunr-languages 添加多语言客户端搜索。它默认启用，但在使用其他插件时必须重新添加到 mkdocs.yml：
plugins:
- search
有关所有设置的列表，请查阅插件文档。
搜索建议
启用搜索建议后，搜索将显示最后一个单词的最可能完成，该单词可以通过 Right 键接受。将以下行添加到 mkdocs.yml：
theme:
features:
- search.suggest
搜索会生成搜索建议作为建议。
设置站点分析
与 Web 上提供的任何其他服务一样，了解项目文档的实际使用方式可能是一个重要的成功因素。MkDocs 材料与 Google Analytics 原生集成，并提供可定制的 cookie 同意和反馈小部件。
谷歌分析
Material for MkDocs 与 Google Analytics 4 原生集成。如果您已经设置了 Google Analytics 并拥有资产，请通过将以下行添加到mkdocs.yml来启用它：
extra:
analytics:
provider: google
property: G-XXXXXXXXXX
https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics
设置博客
Material for MkDocs 使构建博客变得非常容易，既可以作为文档的附属，也可以独立使用。专注于您的内容，而引擎会完成所有繁重的工作，自动生成存档和类别索引、帖子、可配置的分页等。
内置博客插件
内置的博客插件增加了对从文章文件夹构建博客的支持，这些文章使用日期和其他结构化数据进行注释。首先，将以下行添加到 mkdocs.yml：
plugins:
- blog
如果您的 mkdocs.yml 中没有导航 （nav） 定义，则无需执行任何其他作，因为博客插件会自动添加导航。如果您确实定义了导航，则只需向其添加博客索引页面。您不需要也不应该添加单独的博客文章。例如：
nav:
- index.md
- Blog:
- blog/index.md
有关所有设置的列表，请查阅插件文档。
设置标签
Material for MkDocs 增加了对带有标签的页面进行分类的一流支持，这增加了对相关页面进行分组的可能性，并使它们可以通过搜索和专用标签索引被发现。如果您的文档很大，则标记可以帮助更快地发现相关信息。
内置标签插件
内置 tags 插件添加了将任何带有标签的页面分类作为页面 front matter 的一部分的功能。要添加对标签的支持，请将以下行添加到 mkdocs.yml：
plugins:
- tags
有关所有设置的列表，请查阅插件文档。
版本控制
MkDocs 的 Material 通过与外部实用程序（即 mike）集成，可以轻松部署多个版本的项目文档。部署新版本时，旧版本的文档保持不变。
配置
Mike 使部署项目文档的多个版本变得容易。它与 Material for MkDocs原生集成，可以通过 mkdocs.yml 启用：
extra:
version:
provider: mike
设置Header
Material for MkDocs的header可以自定义标题以显示滚动时消失的公告栏，并为进一步配置提供一些选项。它还包括搜索栏和显示项目的 git 存储库的位置，如这些专用指南中所述。
自动隐藏
启用自动隐藏后，当用户滚动超过特定阈值时，标头会自动隐藏，从而为内容留出更多空间。将以下行添加到 mkdocs.yml：
features:
- header.autohide
公告栏
Material for MkDocs包括一个公告栏，这是向用户显示项目新闻或其他重要信息的理想场所。当用户滚动过标题时，该栏将自动消失。要添加公告栏，请扩展主题并覆盖 announce 块，默认情况下该块为空：
{% extends "base.html" %}
{% block announce %}
<!-- Add announcement here, including arbitrary HTML -->
{% endblock %}