选择你的主题

选择并配置主题。

MkDocs 包含两个内置主题（mkdocs 和 readthedocs），如下所述。然而，还有许多第三方主题可供选择。

要选择一个主题，请在你的 mkdocs.yml 配置文件中设置 theme 配置选项。

theme:
  name: readthedocs

mkdocs

默认主题，它是一个自定义的 Bootstrap 主题，支持 MkDocs 的几乎所有功能。

除了默认的主题配置选项，mkdocs 主题还支持以下选项：

color_mode ：将主题的默认颜色模式设置为 light、dark 或 auto 之一。auto 模式将根据用户的设备系统配置在 light 或 dark 之间切换。默认值：light。
user_color_mode_toggle ：在导航栏中启用一个切换菜单，允许用户从浏览器中选择他们偏好的 color_mode（浅色、深色、自动），并在未来的页面加载中保存他们的偏好。切换菜单在首次页面加载时的默认选择是 color_mode 设置的值。默认值：false。
nav_style ：调整顶部导航栏的视觉样式。设置为 primary、dark 或 light 之一。默认值：primary。此选项独立于 color_mode 选项，必须单独定义。
highlightjs ：使用 highlight.js JavaScript 库启用代码块中的源代码高亮显示。默认值：True。
hljs_style ：highlight.js 库为代码块中的源代码高亮显示提供了许多不同的 [样式]（颜色变化）。在 light 模式下设置此选项为所需样式的名称。默认值：github。
hljs_style_dark ：在 dark 模式下设置此选项为所需 highlight.js 样式的名称。默认值：github_dark。
hljs_languages ：默认情况下，highlight.js 仅支持 23 种常见语言。在此处列出其他语言以包含对它们的支持。
```
theme:
  name: mkdocs
  highlightjs: true
  hljs_languages:
    - yaml
    - rust
```
analytics ：定义分析服务的配置选项。目前，仅支持通过 gtag 选项的 Google Analytics v4。
- gtag ：要启用 Google Analytics，请设置为 Google Analytics v4 跟踪 ID，使用 G- 格式。请参阅 Google 的文档以为网站和/或应用设置分析（GA4）或升级到 Google Analytics 4 属性。
```
theme:
  name: mkdocs
  analytics:
    gtag: G-ABC123
```
  当设置为默认值（null）时，Google Analytics 对站点禁用。
shortcuts ：定义键盘快捷键。
```
theme:
  name: mkdocs
  shortcuts:
    help: 191    # ?
    next: 78     # n
    previous: 80 # p
    search: 83   # s
```
所有值必须是数字键码。最好使用所有键盘上都可用的键。你可以使用 https://keycode.info/ 来确定给定键的键码。
- help ：显示一个列出键盘快捷键的帮助模态框。默认值：191 (?)
- next ：导航到“下一页”。默认值：78 (n)
- previous ：导航到“上一页”。默认值：80 (p)
- search ：显示搜索模态框。默认值：83 (s)
navigation_depth ：侧边栏中导航树的最大深度。默认值：2。
locale：用于构建主题的区域设置（语言/位置）。如果你的区域设置尚未支持，它将回退到默认设置。

此主题支持以下区域设置：
- en：英语（默认）
- （参见现有目录 mkdocs/themes/mkdocs/locales/*/）
有关更多信息，请参阅 [本地化你的主题] 指南。

readthedocs

Read the Docs 服务使用的默认主题的克隆，它提供了与其父主题相同的受限功能集。与父主题一样，仅支持两级导航。

ReadTheDocs

除了默认的主题配置选项，readthedocs 主题还支持以下选项：主题支持以下选项：

highlightjs: 使用 highlight.js JavaScript 库在代码块中启用源代码高亮。默认值：True。
hljs_languages: 默认情况下，highlight.js 仅支持 23 种常见语言。在此处列出其他语言以包含对它们的支持。
```
theme:
  name: readthedocs
  highlightjs: true
  hljs_languages:
    - yaml
    - rust
```
analytics: 定义分析服务的配置选项。
- gtag: 要启用 Google Analytics，请设置为 Google Analytics v4 跟踪 ID，使用 G- 格式。请参阅 Google 的文档以为网站和/或应用设置分析（GA4）或升级到 Google Analytics 4 属性。
```
theme:
  name: readthedocs
  analytics:
    gtag: G-ABC123
```
  当设置为默认值（null）时，Google Analytics 对网站禁用。
- anonymize_ip: 要为 Google Analytics 启用匿名 IP 地址，请将此项设置为 True。默认值：False。
include_homepage_in_sidebar: 在侧边栏菜单中列出主页。由于 MkDocs 要求主页在 nav 配置选项中列出，此设置允许在侧边栏中包含或排除主页。请注意，站点名称/徽标始终链接到主页。默认值：True。
prev_next_buttons_location: 可以是 bottom、top、both 或 none 之一。相应地显示“下一页”和“上一页”按钮。默认值：bottom。
navigation_depth: 侧边栏中导航树的最大深度。默认值：4。
collapse_navigation: 仅在侧边栏中包含当前页面的部分标题。默认值：True。
titles_only: 仅在侧边栏中包含页面标题，排除所有页面的部分标题。默认值：False。
sticky_navigation: 如果为 True，则侧边栏会随着您滚动页面而与主要页面内容一起滚动。默认值：True。
locale: 用于构建主题的语言/位置。如果您的语言环境尚未支持，它将回退到默认值。

此主题支持以下语言环境：
- en: 英语（默认）
- （参见现有目录 mkdocs/themes/readthedocs/locales/*/）
有关更多信息，请参阅本地化您的主题指南。
logo: 要在项目中设置徽标而不是纯文本 site_name，请将此变量设置为图像的位置。默认值：null。

第三方主题

第三方主题的列表可以在社区维基页面和排名目录中找到。如果您创建了自己的主题，请将它们添加到那里。

警告：安装 MkDocs 主题意味着安装一个 Python 包并执行作者放在那里的任何代码。因此，请谨慎行事；没有尝试进行沙盒化。

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search