扩展主题#
有许多可用于 Sphinx 的扩展可以增强您的网站或提供强大的自定义功能。在这里，描述了一些 pydata-sphinx-theme 用户常用的自定义功能。
可折叠的警告框#
sphinx-togglebutton 插件为警告框提供了可选的显示/隐藏行为。按照他们的安装说明，然后将其添加到 conf.py 中的 extensions 列表中：
extensions = [
# [...]
"sphinx_togglebutton"
]
然后将 dropdown 类添加到任何警告框指令中（此处以 note 警告框为例）：
备注
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
.. note::
:class: dropdown
Lorem ipsum dolor sit amet, consectetur adipiscing elit.```{note}
:class: dropdown
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```
自定义警告框样式#
docutils（Sphinx 底层的 rST → HTML 引擎）内置了 有限的警告框集合。然而，可以创建具有自定义默认颜色、图标和标题的警告框。
定制标题#
尽管大多数警告框都有默认标题，如 note 或 warning，但 docutils/Sphinx 内置了通用的 admonition 指令。在此主题中，其颜色默认与 note 警告框相同，并且有铃铛图标：
Custom title!
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
标题与 .. admonition:: 指令在同一行指定：
.. admonition:: Custom title!
Lorem ipsum dolor sit amet, consectetur adipiscing elit.```{admonition} Custom title!
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```
使用语义颜色名称进行样式设置#
您可以使用 主题的语义颜色名称 作为类，重新设置任何警告框的样式以匹配任何内置警告框类型（这对于自定义标题的警告框最有用）：
Custom title with "warning" style
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
请注意，它会同时更新颜色和图标。有关所有语义颜色名称的列表，请参阅 主题变量和 CSS。
.. admonition:: Custom title with "warning" style
:class: warning
Lorem ipsum dolor sit amet, consectetur adipiscing elit.```{admonition} Custom title with "warning" style
:class: warning
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```
该主题为 标准 docutils 警告框类型 （attention、caution 等）定义了类，并且还支持 seealso 和 todo 警告框（有关所有内置警告框样式的演示，请参阅 Admonitions）。
自定义颜色#
除了预定义的语义颜色类（参见上一节），您还可以通过定义自己的 CSS 类为任何警告框添加自定义颜色。示例：
Admonition with custom "olive" color
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
为此，您需要将类添加到 custom.css 文件中，如下例所示。确保对 border-color 和 color 使用相同的颜色，并对 background-color 使用不同的色调：
.. admonition:: Admonition with custom "olive" color
:class: admonition-olive
Lorem ipsum dolor sit amet, consectetur adipiscing elit.```{admonition} Admonition with custom "olive" color
:class: admonition-olive
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```
并将以下内容添加到您的 custom.css 文件中：
/* <your static path>/custom.css */
div.admonition.admonition-olive {
border-color: hsl(60deg 100% 25%);
}
div.admonition.admonition-olive > .admonition-title {
background-color: hsl(60deg 100% 14%);
color: white;
}
div.admonition.admonition-olive > .admonition-title::after {
color: hsl(60deg 100% 25%);
}使用自定义图标#
自定义图标的过程与自定义颜色类似：在您的 custom.css 文件中创建新的 CSS 类。该主题支持 fontawesome v6 图标 （“免费”和“品牌”集）。要使用图标，请将其 Unicode 值复制到您的自定义类中，如下面的 CSS 选项卡所示：
.. admonition:: Check out my custom icon
:class: admonition-icon
Lorem ipsum dolor sit amet, consectetur adipiscing elit.```{admonition} Check out my custom icon
:class: admonition-icon
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```
并将以下 CSS 添加到您的 custom.css 文件中：
/* <your static path>/custom.css */
div.admonition.admonition-icon > .admonition-title::after {
content: "\f24e"; /* the fa-scale icon */
}结合所有三种自定义#
在这里，演示了具有自定义图标、颜色和标题的警告框（并且使其可折叠）。请注意，多个警告框类名之间用空格分隔：
YouTube
.. admonition:: YouTube
:class: dropdown admonition-youtube
.. youtube:: dQw4w9WgXcQ````{admonition} YouTube
:class: dropdown admonition-youtube
```{youtube} dQw4w9WgXcQ
```
````
并将以下 CSS 添加到您的 custom.css 文件中：
/* <your static path>/custom.css */
div.admonition.admonition-youtube {
border-color: hsl(0deg 100% 50%); /* YouTube red */
}
div.admonition.admonition-youtube > .admonition-title {
background-color: hsl(0deg 99% 18%);
color: white;
}
div.admonition.admonition-youtube > .admonition-title::after {
color: hsl(0deg 100% 50%);
content: "\f26c"; /* fa-solid fa-tv */
}