改变颜色¶

¥Changing the colors¶

与任何合适的 Material Design 实现一样，Material for MkDocs 支持 Google 的原始调色板，可通过mkdocs.yml轻松配置。此外，您还可以使用CSS 变量，仅用几行 CSS 代码即可自定义颜色，以符合您的品牌标识。

¥As any proper Material Design implementation, Material for MkDocs supports Google's original color palette, which can be easily configured through mkdocs.yml. Furthermore, colors can be customized with a few lines of CSS to fit your brand's identity by using CSS variables.

配置¶

¥Configuration¶

调色板¶

¥Color palette¶

配色方案¶

¥Color scheme¶

5.2.0默认

¥5.2.0 default

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

¥Material for MkDocs supports two color schemes: a light mode, which is just called default, and a dark mode, which is called slate. The color scheme can be set via mkdocs.yml:

theme:
  palette:
    scheme: default

单击图块即可更改配色方案：

¥Click on a tile to change the color scheme:

原色¶

¥Primary color¶

0.2.0靛蓝

¥0.2.0 indigo

主色用于标题、侧边栏、文本链接和其他几个组件。要更改主色，请在mkdocs.yml中将以下值设置为有效的颜色名称：

¥The primary color is used for the header, the sidebar, text links and several other components. In order to change the primary color, set the following value in mkdocs.yml to a valid color name:

theme:
  palette:
    primary: indigo

单击图块即可更改主颜色：

¥Click on a tile to change the primary color:

请参阅下面的指南，了解如何设置自定义颜色。

¥See our guide below to learn how to set custom colors.

强调色¶

¥Accent color¶

0.2.0靛蓝

¥0.2.0 indigo

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

¥The accent color is used to denote elements that can be interacted with, e.g. hovered links, buttons and scrollbars. It can be changed in mkdocs.yml by choosing a valid color name:

theme:
  palette:
    accent: indigo

单击图块即可更改强调色：

¥Click on a tile to change the accent color:

请参阅下面的指南，了解如何设置自定义颜色。

¥See our guide below to learn how to set custom colors.

调色板切换¶

¥Color palette toggle¶

7.1.0 。拉链

¥7.1.0 .zip

提供明暗色调的配色方案，让您的文档在一天中的不同时间都能轻松阅读，方便用户进行选择。将以下几行添加到mkdocs.yml中：

¥Offering a light and dark color palette makes your documentation pleasant to read at different times of the day, so the user can choose accordingly. Add the following lines to mkdocs.yml:

theme:
  palette: # (1)!

    # Palette toggle for light mode
    - scheme: default
      toggle:
        icon: material/brightness-7 # (2)!
        name: Switch to dark mode

    # Palette toggle for dark mode
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

请注意， theme.palette设置现在定义为列表。
输入几个关键字，使用我们的图标搜索找到完美的图标，然后单击短代码将其复制到剪贴板：

此配置将在搜索栏旁边呈现一个调色板切换按钮。请注意，您还可以为每个调色板分别定义主色调和强调色调的设置。

¥Note that the theme.palette setting is now defined as a list.

必须为每个切换设置以下属性：

¥Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:

icon

此属性必须指向有效的图标路径，该路径引用了主题捆绑的任何图标，否则构建将失败。一些常见的组合：

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

name

此属性用作切换按钮的title属性，应将其设置为可识别的名称以提高可访问性。它将呈现为工具提示。

系统偏好设置¶

¥System preference¶

7.1.0 。拉链

¥This configuration will render a color palette toggle next to the search bar. Note that you can also define separate settings for primary and accent per color palette.

通过使用媒体查询，每个调色板都可以与用户系统对明暗外观的偏好设置关联。只需在mkdocs.yml中的scheme定义旁边添加一个media属性即可：

¥The following properties must be set for each toggle:

theme:
  palette:

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

当用户首次访问你的网站时，媒体查询会按照其定义的顺序进行评估。第一个匹配的媒体查询将选择默认调色板。

¥ This property must point to a valid icon path referencing any icon bundled with the theme, or the build will not succeed. Some popular combinations:

自动亮/暗模式¶

¥Automatic light / dark mode¶

9.5.0 。拉链

¥ This property is used as the toggle's title attribute and should be set to a discernable name to improve accessibility. It's rendered as a tooltip.

较新的操作系统允许在白天和夜晚自动切换明暗外观。Material for MkDocs 增加了对自动明暗模式的支持，将调色板选择委托给用户的操作系统。将以下几行添加到mkdocs.yml中：

¥7.1.0 .zip

theme:
  palette:

    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default # (1)!
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to system preference

您还可以为每个调色板定义单独的主要颜色和强调颜色设置，即为明暗模式定义不同的颜色。
¥You can also define separate settings for primary and accent per color palette, i.e. different colors for light and dark mode.

现在，每次操作系统在明暗外观之间切换时，MkDocs 的材料都会更改调色板，即使用户没有重新加载网站。

¥Each color palette can be linked to the user's system preference for light and dark appearance by using a media query. Simply add a media property next to the scheme definition in mkdocs.yml:

定制¶

¥Customization¶

自定义颜色¶

¥Custom colors¶

5.0.0 .zip

¥When the user first visits your site, the media queries are evaluated in the order of their definition. The first media query that matches selects the default color palette.

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

¥9.5.0 .zip

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

¥Newer operating systems allow to automatically switch between light and dark appearance during day and night times. Material for MkDocs adds support for automatic light / dark mode, delegating color palette selection to the user's operating system. Add the following lines to mkdocs.yml:

theme:
  palette:
    primary: custom

假设你YouTube ，并希望将主色调设置为品牌的调色板。只需添加：

¥Material for MkDocs will now change the color palette each time the operating system switches between light and dark appearance, even when the user doesn't reload the site.

docs/stylesheets/extra.css mkdocs.yml

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

extra_css:
  - stylesheets/extra.css

请参阅包含颜色定义的文件以获取所有 CSS 变量的列表。

¥5.0.0 .zip

自定义配色方案¶

¥Custom color schemes¶

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

¥Material for MkDocs implements colors using CSS variables (custom properties). If you want to customize the colors beyond the palette (e.g. to use your brand-specific colors), you can add an additional style sheet and tweak the values of the CSS variables.

docs/stylesheets/extra.css mkdocs.yml

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

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

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

¥First, set the primary or accent values in mkdocs.yml to custom, to signal to the theme that you want to define custom colors, e.g., when you want to override the primary color:

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

hue值必须在[0, 360]范围内
¥The hue value must be in the range of [0, 360]