改变颜色

作为一个合适的 Material Design 实现，Material for MkDocs 支持谷歌原始的颜色调色板，可以通过 mkdocs.yml 文件轻松配置。此外，可以使用几行 CSS 自定义颜色，以符合品牌的身份标识，使用CSS 变量。

配置

颜色调色板

颜色方案

默认值：default

Material for MkDocs 支持两种颜色方案：浅色模式，也称为 default，和 深色模式，称为 slate。可以通过 mkdocs.yml 设置颜色方案：

theme:
  palette:
    scheme: default

点击瓷砖以更改颜色方案：

主要颜色

默认值：indigo

主要颜色用于页眉、侧边栏、文本链接和其他一些组件。为了更改主要颜色，将以下值设置为有效的颜色名称：

theme:
  palette:
    primary: indigo

点击瓷砖以更改主要颜色：

查看下面的指南，了解如何设置自定义颜色。

强调颜色

默认值：indigo

强调颜色用于表示可交互的元素，例如悬停链接、按钮和滚动条。可以通过在 mkdocs.yml 中选择有效的颜色名称来更改强调颜色：

theme:
  palette:
    accent: indigo

点击瓷砖以更改强调颜色：

查看下面的指南，了解如何设置自定义颜色。

颜色调色板切换

默认值：无

提供浅色和深色颜色调色板，使您的文档在不同时间段更加舒适阅读，用户可以根据需要进行选择。将以下行添加到 mkdocs.yml 文件中：

theme:
  palette: # (1)!
    # 浅色模式的调色板切换
    - scheme: default
      toggle:
        icon: material/brightness-7 # (2)!
        name: 切换到深色模式

    # 深色模式的调色板切换
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式

注意，theme.palette 设置现在被定义为列表。
输入一些关键词，使用我们的图标搜索找到完美的图标，并点击简码将其复制到剪贴板：

此配置将在搜索栏旁边呈现一个颜色调色板切换。请注意，您还可以为每个颜色调色板单独定义primary和accent设置。

对于每个切换，必须设置以下属性：

icon

默认值：无 · 必需 - 此属性必须指向一个有效的图标路径，引用主题中捆绑的任何图标，否则构建将无法成功。一些常见的组合有：

+ - material/brightness-7 + material/brightness-4
+ - material/toggle-switch + material/toggle-switch-off-outline
+ - material/weather-night + material/weather-sunny
+ - material/eye + material/eye-outline
+ - material/lightbulb + material/lightbulb-outline

name

默认值：无 · 必需 - 此属性用作切换的 title 属性，应设置为可辨识的名称以提高可访问性。它被呈现为工具提示。

系统首选项

7.1.0 · 默认值：无

每个颜色调色板可以与用户的浅色和深色外观系统首选项相关联，使用媒体查询。只需在 mkdocs.yml 中的 scheme 定义旁边添加一个 media 属性：

theme:
  palette:
    # 浅色模式的调色板切换
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式

    # 深色模式的调色板切换
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式

当用户首次访问您的站点时，媒体查询按照定义的顺序进行评估。第一个匹配的媒体查询将选择默认的颜色方案。

自动浅色/深色模式

仅赞助商 · insiders-4.18.0 · 实验性

较新的操作系统允许在白天和黑夜时间自动在浅色和深色外观之间切换。内幕添加了对自动浅色/深色模式的支持，将颜色调色板选择委托给用户的操作系统。将以下行添加到 mkdocs.yml 文件中：

theme:
  palette:
    # 自动模式的调色板切换
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: 切换到浅色模式

    # 浅色模式的调色板切换
    - media: "(prefers-color-scheme: light)"
      scheme: default # (1)!
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式

    # 深色模式的调色板切换
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: 切换到系统首选项

您还可以为每个颜色调色板定义primary和accent的单独设置，即为浅色和深色模式定义不同的颜色。

Material for MkDocs 现在将在操作系统在浅色和深色外观之间切换时更改颜色调色板，即使用户不重新加载站点也会生效。

自定义

自定义颜色

Material for MkDocs 使用CSS 变量（自定义属性）实现颜色。如果您想在调色板之外自定义颜色（例如使用品牌特定的颜色），可以添加一个额外的样式表并调整 CSS 变量的值。

首先，在 mkdocs.yml 中将 primary 或 accent 的值设置为 custom，以向主题指示您要定义自定义颜色，例如，当您想要覆盖 primary 颜色时：

theme:
  palette:
    primary: custom

假设您是 YouTube，希望将主要颜色设置为您品牌的调色板。只需添加以下内容：

docs/stylesheets/extra.css

:root {
  --md-primary-fg-color:        #EE0F0F;
  --md-primary-fg-color--light: #ECB7B7;
  --md-primary-fg-color--dark:  #90030C;
}

mkdocs.yml

extra_css:
  - stylesheets/extra.css

请参阅包含颜色定义的文件，了解所有 CSS 变量的列表。

自定义颜色方案

除了覆盖特定颜色之外，您还可以通过将定义包装在 [data-md-color-scheme="..."] 属性选择器中来创建自己的命名颜色方案，然后可以通过 mkdocs.yml 中的颜色方案部分进行设置：

docs/stylesheets/extra.css

[data-md-color-scheme="youtube"] {
  --md-primary-fg-color:        #EE0F0F;
  --md-primary-fg-color--light: #ECB7B7;
  --md-primary-fg-color--dark:  #90030C;
}

mkdocs.yml

theme:
  palette:
    scheme: youtube
extra_css:
  - stylesheets/extra.css

此外，slate 颜色方案使用 hsla 颜色函数定义了所有颜色，并从 --md-hue CSS 变量中推导出其颜色。您可以使用以下方式调整 slate 主题：

[data-md-color-scheme="slate"] {
  --md-hue: 210; /* (1)! */
}

hue 值必须在 [0, 360] 范围内