主题变量和 CSS#

本节介绍几种方法，可以通过自定义 CSS 和主题变量来控制主题的外观和风格。

自定义 CSS 样式表#

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

另请参阅

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

要添加自定义样式表，请执行以下步骤

在 _static/css/custom.css 中创建一个 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 主题使用可访问的 pygments 样式作为其默认语法突出显示主题。可访问的 pygments 主题旨在满足 WCAG AA 或 AAA 的颜色对比标准，其中一些包含的主题也适用于色盲用户或低光照条件。您可以在可访问的 pygments 演示页面上查看所有可用的样式。

危险

此主题将覆盖本机 Sphinx 选项 pygments_style。