主题变量和 CSS#

本节介绍了几种通过您自己的 CSS 和主题变量控制主题外观的方法。

定制 CSS 样式表#

你可以通过创建自定义样式表来定制主题的 CSS。Sphinx 在构建你的网站时将使用这个样式表。该样式表中的任何规则都将覆盖默认主题的规则。

参见

有关在您的站点中链接静态 CSS 和 JS 资源的更深入指南，请参阅添加自定义 CSS 和 JS 资源。

要添加自定义样式表，请按照以下步骤操作：

创建 CSS 样式表 在 _static/css/custom.css 中，并根据需要更新CSS规则。
将样式表附加到您的 Sphinx 构建中。将以下内容添加到 conf.py 文件中：
```
html_static_path = ['_static']

html_css_files = [
    'css/custom.css',
]
```

当您构建文档时，此样式表现在应该已被激活。

CSS 主题变量#

该主题定义了多个 CSS 变量，可用于快速控制整个文档的行为和显示。

这些变量基于基本的 Bootstrap CSS 变量，并扩展了一些主题特定的变量。

基本变量#

请按照以下步骤更新基础变量：

添加自定义 CSS 样式表。将在此处配置变量。
在 html 部分下，添加您希望更新的变量。例如，要更改基础字体大小，您可以在 custom.css 文件中添加以下内容：
```
html {
    --pst-font-size-base: 17px;
}
```

重要

请注意，该主题是使用 CSS变量定义的，而不是 SASS变量。

如果您希望在浅色主题和深色主题之间实现不同的效果，请参考本文档中的管理主题部分。

有关您可以覆盖的主题变量的完整列表，请参阅主题变量默认CSS文件：

html {
  /*****************************************************************************
  * Overall Layout Variables
  */

  // Header height will impact the top offset for many sections
  // Article header is 66% of Header
  --pst-header-height: 4rem;
  --pst-header-article-height: calc(var(--pst-header-height) * 2 / 3);
  --pst-sidebar-secondary: 17rem;
}

/*******************************************************************************
* Breakpoints that trigger UI changes
*
* Note that media-breakpoint-down begins at the next highest level!
* So we should choose a media-breakpoint-down one *lower* than when we want to start
* example: media-breakpoint-up(md) and media-breakpoint-down(sm) trigger at the same time
* ref: https://github.com/twbs/bootstrap/issues/31214
*/
$breakpoint-sidebar-primary: lg; // When we collapse the primary sidebar
$breakpoint-sidebar-secondary: xl; // When we collapse the secondary sidebar
$breakpoint-page-width: 88rem; // taken from sphinx-basic-ng, which we are ultimately going to inherit

/*******************************************************************************
* Define the animation behaviour
*/
$animation-time: 200ms;

/*******************************************************************************
* UI shaping and padding
*/
$admonition-border-radius: 0.25rem;

// In this theme, some focus rings have rounded corners while others do not.
// This variable sets the border radius for the rounded focus rings.
$focus-ring-radius: 0.125rem; // 2px at 100% zoom and 16px base font.

$navbar-link-padding-y: 0.25rem;

// Ensure that there is no overlap of bumper disks (smallest circle that
// contains the bounding box of the interactive element).
// - https://github.com/Quansight-Labs/czi-scientific-python-mgmt/issues/81#issuecomment-2251325783
$nav-icon-column-gap: 1.12rem;

// Determines vertical space between entries in both the section (left/primary
// sidebar) and page (right/secondary sidebar) table of contents
$toc-item-padding-y: 0.25rem;

html {
  /*****************************************************************************
  * Font features used in this theme
  */

  // base font size - applied at body/html level
  --pst-font-size-base: 1rem;

  // heading font sizes based on a medium contrast type scale
  // - see: https://github.com/Quansight-Labs/czi-scientific-python-mgmt/issues/97#issuecomment-2310531483
  --pst-font-size-h1: 2.625rem;
  --pst-font-size-h2: 2.125rem;
  --pst-font-size-h3: 1.75rem;
  --pst-font-size-h4: 1.5rem;
  --pst-font-size-h5: 1.25rem;
  --pst-font-size-h6: 1rem;

  // smaller than heading font sizes
  --pst-font-size-milli: 0.9rem;

  // Sidebar styles
  --pst-sidebar-font-size: 0.9rem;
  --pst-sidebar-font-size-mobile: 1.1rem;
  --pst-sidebar-header-font-size: 1.2rem;
  --pst-sidebar-header-font-weight: 600;

  // Admonition styles
  --pst-admonition-font-weight-heading: 600;

  // Font weights
  --pst-font-weight-caption: 300;
  --pst-font-weight-heading: 600;

  // Font family
  // These are adapted from https://systemfontstack.com/ */
  --pst-font-family-base-system: -apple-system, "BlinkMacSystemFont", "Segoe UI",
    "Helvetica Neue", "Arial", sans-serif, "Apple Color Emoji", "Segoe UI Emoji",
    "Segoe UI Symbol";
  --pst-font-family-monospace-system: "SFMono-Regular", "Menlo", "Consolas",
    "Monaco", "Liberation Mono", "Lucida Console", monospace;
  --pst-font-family-base: var(--pst-font-family-base-system);
  --pst-font-family-heading: var(--pst-font-family-base-system);
  --pst-font-family-monospace: var(--pst-font-family-monospace-system);
}

$line-height-body: 1.65;
$fa-font-path: "vendor/fontawesome/webfonts/";

html {
  /*****************************************************************************
  * Icon
  */

  // Font size across all icons
  --pst-font-size-icon: 1.5rem;

  // Font Awesome default icons
  --pst-icon-check-circle: "\f058"; // fa-solid fa-circle-check
  --pst-icon-info-circle: "\f05a"; // fa-solid fa-circle-info
  --pst-icon-exclamation-triangle: "\f071"; // fa-solid fa-triangle-exclamation
  --pst-icon-exclamation-circle: "\f06a"; // fa-solid fa-circle-exclamation
  --pst-icon-times-circle: "\f057"; // fa-solid fa-circle-xmark
  --pst-icon-lightbulb: "\f0eb"; // fa-solid fa-lightbulb
  --pst-icon-download: "\f019"; // fa-solid fa-download
  --pst-icon-angle-left: "\f104"; // fa-solid fa-angle-left
  --pst-icon-angle-right: "\f105"; // fa-solid fa-angle-right
  --pst-icon-external-link: "\f35d"; // fa-solid fa-up-right-from-square
  --pst-icon-search-minus: "\f010"; // fa-solid fa-magnifying-glass-minus
  --pst-icon-github: "\f09b"; // fa-brands fa-github
  --pst-icon-gitlab: "\f296"; // fa-brands fa-gitlab
  --pst-icon-share: "\f064"; // fa-solid fa-share
  --pst-icon-bell: "\f0f3"; // fa-solid fa-bell
  --pst-icon-pencil: "\f303"; // fa-solid fa-pencil

  // Bootstrap icons
  --pst-breadcrumb-divider: "\f105";
}

html {
  /*****************************************************************************
  * Admonitions
  **/

  --pst-icon-admonition-default: var(--pst-icon-bell);
  --pst-icon-admonition-note: var(--pst-icon-info-circle);
  --pst-icon-admonition-attention: var(--pst-icon-exclamation-circle);
  --pst-icon-admonition-caution: var(--pst-icon-exclamation-triangle);
  --pst-icon-admonition-warning: var(--pst-icon-exclamation-triangle);
  --pst-icon-admonition-danger: var(--pst-icon-exclamation-triangle);
  --pst-icon-admonition-error: var(--pst-icon-times-circle);
  --pst-icon-admonition-hint: var(--pst-icon-lightbulb);
  --pst-icon-admonition-tip: var(--pst-icon-lightbulb);
  --pst-icon-admonition-important: var(--pst-icon-exclamation-circle);
  --pst-icon-admonition-seealso: var(--pst-icon-share);
  --pst-icon-admonition-todo: var(--pst-icon-pencil);
}

html {
  /*****************************************************************************
  * versionmodified
  **/

  --pst-icon-versionmodified-default: var(--pst-icon-exclamation-circle);
  --pst-icon-versionmodified-added: var(--pst-icon-exclamation-circle);
  --pst-icon-versionmodified-changed: var(--pst-icon-exclamation-circle);
  --pst-icon-versionmodified-deprecated: var(--pst-icon-exclamation-circle);
}

颜色变量#

该主题为主色和辅色分别指定了颜色变量（--pst-color-primary 和 --pst-color-secondary）。这些颜色旨在整个主题中视觉上相互补充，如果您修改这些颜色，请选择彼此搭配良好的颜色。此外，还有其他多个颜色变量用于控制警告、链接、菜单项等的颜色。

每个颜色变量都有两个值，一个对应‘浅色’主题，另一个对应‘深色’主题。这些值在整个主题的许多元素中被用于定义文本颜色、背景颜色等。

以下是主题中可用颜色的概览（切换主题模式以查看浅色和深色版本）。

primary secondary accent success info warning danger background on-background surface on-surface target

要为浅色和深色主题修改这些变量的颜色，请添加自定义CSS样式表，并采用如下结构：

html[data-theme="light"] {
    --pst-color-primary: black;
}

html[data-theme="dark"] {
    --pst-color-primary: white;
}

该主题在浅色主题模式下使用阴影来表现层次感，而在深色主题模式下则使用透明度。它定义了4个颜色变量，用于在文档中构建叠加效果。

background：文档最底层表面的颜色。
on-background：位于此背景之上的元素（例如深色模式下的顶部导航栏）。
surface：在浅色主题模式下，位于背景上并带有浅灰色的元素。此颜色在深色主题中保持不变（例如代码块指令）。
on-surface：位于 surface 元素之上的元素（例如侧边栏指令）。

以下图片将帮助您理解这些叠加层：

background

on-background

surface

on-surface

有关您可以覆盖的主题颜色的完整列表，请参阅 PyData主题CSS颜色样式表。

配置 Pygments 主题#

由于Sphinx主题支持多种模式，可以通过修改 pygments_light_style 和 pygments_dark_style 来分别为每种模式调整代码高亮颜色。您可以在此 Pygments演示页面上查看可用的Pygments颜色。

html_theme_options = {
   ...
   "pygments_light_style": "tango",
   "pygments_dark_style": "monokai"
}

请注意，PyData Sphinx 主题默认使用 accessible pygments 样式进行语法高亮显示。这些 accessible pygments 主题旨在满足 WCAG AA或AAA标准的颜色对比度要求，其中一些主题还适合色盲用户或低光环境使用。您可以在 accessible pygments演示页面上查看所有可用的样式。

危险

Sphinx的原生选项 pygments_style 将被此主题覆盖。