Theme variables and CSS#

This section covers a few ways that you can control the look and feel of your theme via your own CSS and theme variables.

Custom CSS Stylesheets#

You may customize the theme’s CSS by creating a custom stylesheet that Sphinx uses to build your site. Any rules in this style-sheet will over-ride the default theme rules.

To add a custom stylesheet, follow these steps:

  1. Create a CSS stylesheet in _static/css/custom.css, and add the CSS rules you wish.

  2. Attach the stylesheet to your Sphinx build. Add the following to conf.py

    html_static_path = ['_static']

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

When you build your documentation, this stylesheet should now be activated.

CSS theme variables#

This theme defines several CSS variables that can be used to quickly control behavior and display across your documentation.

These are based on top of the basic Bootstrap CSS variables extended with some theme specific variables.

base variables#

In order to change a variable, follow these steps:

  1. Add a custom CSS stylesheet. This is where we’ll configure the variables.

  2. Underneath a html section, add the variables you wish to update. For example, to update the base font size, you might add this to custom.css:

    html {
    --pst-font-size-base: 17px;
}

Important

Note that these are CSS variables and not SASS variables. The theme is defined with CSS variables, not SASS variables! Refer to the previous section if you desire a different behavior between the light and dark theme.

For a complete list of the theme variables that you may override, see the theme variables defaults CSS file:

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

  // Header height will impact the top offset for many sections
  // Article header is 66% of Header
  --pst-header-height: 3rem;
  --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;

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

  // base font size - applied at body/html level
  --pst-font-size-base: 15px;

  // heading font sizes
  --pst-font-size-h1: 36px;
  --pst-font-size-h2: 32px;
  --pst-font-size-h3: 26px;
  --pst-font-size-h4: 21px;
  --pst-font-size-h5: 18px;
  --pst-font-size-h6: 16px;

  // smaller than heading font sizes
  --pst-font-size-milli: 12px;

  // Sidebar styles
  --pst-sidebar-font-size: 0.9em;
  --pst-sidebar-font-size-mobile: 1.2em;
  --pst-sidebar-header-font-size: 1.2em;
  --pst-sidebar-header-font-weight: 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);
}

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
}

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);
}

Color variables#

There are two special color variables for primary and secondary theme colors (--pst-color-primary and --pst-color-secondary, respectively). These are meant to complement one another visually across the theme, if you modify these, choose colors that look good when paired with one another. There are also several other color variables that control color for admonitions, links, menu items, etc.

Each color variable has two values, one corresponding to the “light” and one for the “dark” theme. These are used throughout many of the theme elements to define text color, background color, etc.

Here is an overview of the colors available in the theme (change theme mode to switch from light to dark versions).

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

To modify the colors for these variables for light and dark themes, add a custom CSS stylesheet with a structure like so:

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

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

This theme uses shadows to convey depth in the light theme mode and opacity in the dark one. It defines 4 color variables that help build overlays in your documentation.

  • background: color of the back-most surface of the documentation

  • on-background elements that are set on top of this background (e.g. the header navbar on dark mode).

  • surface elements set on the background with a light-grey color in the light theme mode. this color has been kept in the dark theme (e.g. code-block directives).

  • on-surface elements that are on top of surface elements (e.g. sidebar directives).

The following image should help you understand these overlays:

background

on-background

surface

on-surface

For a complete list of the theme colors that you may override, see the PyData theme CSS colors stylesheet.

Configure pygments theme#

As the Sphinx theme supports multiple modes, the code highlighting colors can be modified for each one of them by modifying the pygment_light_style and pygment_dark_style. You can check available Pygments colors on this page.

html_theme_options = {
   ...
   "pygment_light_style": "tango",
   "pygment_dark_style": "monokai"
}

Danger

The native Sphinx option pygments_style will be overwritten by this theme.