浅色和深色主题#

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

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

配置默认主题模式#

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

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

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

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

提示

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

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

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

危险

主题仍然是一个 Beta 功能，因此与颜色主题相关的变量将来可能会更改。对自定义进行的更改不保证向后兼容。

要以依赖于主题的方式自定义页面元素的 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 文档。