浅色和深色主题#

您可以使用内置的“深色”和“浅色”模式更改此主题的主要背景/前景颜色。这些由导航标题中的按钮控制，具有以下选项：

具有明亮背景和深色文本/UI 元素的 light 主题
具有深色背景和浅色文本/UI 元素的 dark 主题
auto：文档主题将遵循您设置的系统默认值

配置默认主题模式#

默认情况下，访问您的文档的用户将使用主题模式 auto。这将根据用户的系统设置选择主题，如果未找到系统设置，则默认为 light。

如果您希望使用不同的默认主题模式，请将 default_mode 配置设置为 auto、dark、light 之一。例如：

html_context = {
   # ...
   "default_mode": "light"
}

有关更多信息，请参阅浅色和深色主题。

小技巧

要完全移除主题管理，请将 default_mode 配置为您在文档中想要的值（light 或 dark），然后从标题导航栏配置的 navbar_end 部分移除主题切换器：

html_theme_options {
    ...
    # Note we have omitted `theme-switcher` below
    "navbar_end": ["navbar-icon-links"]
}

自定义浅色和深色主题的 CSS#

危险

主题化仍处于测试阶段，因此与颜色主题化相关的变量将来可能会发生变化。进行自定义时，不保证向后兼容性。

要以依赖于主题的方式自定义页面元素的 CSS，请使用 html[data-theme='<THEME>'] CSS 选择器。例如，为浅色和深色主题定义不同的背景颜色：

/* anything related to the light theme */
html[data-theme="light"] {

    /* whatever you want to change */
    background-color: white;
}

/* anything related to the dark theme */
html[data-theme="dark"] {

    /* whatever you want to change */
    background-color: black;
}

此主题中使用的颜色的完整列表可在 CSS 样式部分中找到。

依赖于主题的图像和内容#

可以为浅色和深色模式使用不同的内容，以便内容仅在特定主题激活时显示。如果您的内容依赖于主题的样式（例如具有浅色或深色背景的 PNG 图像），这将非常有用。

有 两个 CSS 辅助类 可以将页面上的项目指定为特定于主题的。它们是：

only-dark：仅在深色主题激活时显示元素。
only-light：仅在浅色主题激活时显示元素。

例如，以下页面内容定义了两个图像，每个图像都使用上述类之一。更改主题后，应显示新图像。

rst

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
    :class: only-dark

.. image:: https://source.unsplash.com/200x200/daily?cute+dog
    :class: only-light

markdown

```{image} https://source.unsplash.com/200x200/daily?cute+cat
:class: only-dark
```

```{image} https://source.unsplash.com/200x200/daily?cute+dog
:class: only-light
```

https://source.unsplash.com/200x200/daily?cute+cat

https://source.unsplash.com/200x200/daily?cute+dog

适用于两种主题的图片和内容#

当 深色主题 激活时，不支持深色模式的图像将自动添加白色背景以确保图像内容可见，并且它们的亮度将通过滤镜降低。

如果您的图像适合深色主题，请如上所述添加 CSS 类 only-dark。如果您的图像适合浅色和深色主题，请添加 CSS 类 dark-light 以使您的图像与主题无关。

例如，这是未添加此辅助类的图像。切换到深色主题时，将出现灰色背景。

rst

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
    :class: p-2

markdown

```{image} https://source.unsplash.com/200x200/daily?cute+cat
:class: p-2
```

这是添加了此类的相同图像：

rst

.. image:: https://source.unsplash.com/200x200/daily?cute+cat
    :class: dark-light

markdown

```{image} https://source.unsplash.com/200x200/daily?cute+cat
:class: dark-light p-2
```

定义自定义 JavaScript 以响应主题更改#

您可以定义 JavaScript 事件钩子，该钩子将在主题更改时运行您的代码。如果您需要更改无法通过 CSS 规则定义的页面元素，这将非常有用。例如，要在 data-theme 更改时更改图像源（例如徽标），可以使用如下代码片段：

rst

.. raw:: html

    <script type="text/javascript">
    var observer = new MutationObserver(function(mutations) {
        const dark = document.documentElement.dataset.theme == 'dark';
        document.getElementsByClassName('mainlogo')[0].src = dark ? '_static/my_logo_dark.svg' : "_static/my_logo_light.svg";
    })
    observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']});
    </script>
    <link rel="preload" href="_static/my_logo_dark.svg" as="image">

.. image:: _static/my_logo_light.svg
    :alt: My Logo
    :class: logo, mainlogo
    :align: center

markdown

<script type="text/javascript">
var observer = new MutationObserver(function(mutations) {
    const dark = document.documentElement.dataset.theme == 'dark';
    document.getElementsByClassName('mainlogo')[0].src = dark ? '_static/my_logo_dark.svg' : "_static/my_logo_light.svg";
})
observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']});
</script>
<link rel="preload" href="_static/my_logo_dark.svg" as="image">

```{image} _static/my_logo_light.svg
:alt: My Logo
:class: logo, mainlogo
:align: center
```

JavaScript 响应 data-theme 更改以更改 img，并且 link 用于预加载深色图像。有关更多信息，请参阅 MutationObserver 文档。