扩展主题#
Sphinx 有许多可用的扩展，可以增强您的网站或提供强大的自定义功能。在这里，我们描述一些 pydata-sphinx-theme 用户常用的自定义功能。
可折叠警示框#
该 sphinx-togglebutton 扩展为警示框提供可选的显示/隐藏行为。按照他们的安装说明操作，然后将其添加到您的 conf.py 中的 extentions 列表中
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，但通用 admonition 指令内置于 docutils/Sphinx 中。在此主题中，其颜色默认为与 note 警示框相同的颜色，并且有一个铃铛图标
自定义标题！
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.
```
使用语义颜色名称进行样式设置#
您可以通过使用任何 主题的语义颜色名称 作为类来重新设置任何警示框的样式以匹配任何内置警示框类型（这对于自定义标题的警示框最有用）
具有“警告”样式的自定义标题
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 警示框（有关所有内置警示框样式的演示，请参阅 警示框）。
自定义颜色#
除了预定义的语义颜色类（请参阅上一节）之外，您还可以通过定义自己的 CSS 类为任何警示框添加定制颜色。示例
具有自定义“橄榄色”的警示框
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 */
}