Customizing the theme#

In addition to the configuration options detailed at Configuration, it is also possible to customize the HTML layout and CSS style of the theme.

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 across your documentation.

These are based on top of the basic Bootstrap CSS variables extended with some theme specific variables. An overview of all variables and every default is defined in the pydata default CSS variables file.

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 :root section, add the variables you wish to update. For example, to update the base font size, you might add this to custom.css:

    :root {
    --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!

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

/* Provided by Sphinx's 'basic' theme, and included in the final set of assets */
@import "../basic.css";

:root {
  /*****************************************************************************
  * Theme config
  **/
  --pst-header-height: 60px;

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

  /* 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 then heading font sizes*/
  --pst-font-size-milli: 12px;

  --pst-sidebar-font-size: 0.9em;
  --pst-sidebar-caption-font-size: 0.9em;

  /*****************************************************************************
  * 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);
  --pst-font-family-monospace: var(--pst-font-family-monospace-system);

  /*****************************************************************************
  * Color
  *
  * Colors are defined in rgb string way, "red, green, blue"
  **/
  --pst-color-primary: 19, 6, 84;
  --pst-color-success: 40, 167, 69;
  --pst-color-info: 0, 123, 255; /*23, 162, 184;*/
  --pst-color-warning: 255, 193, 7;
  --pst-color-danger: 220, 53, 69;
  --pst-color-text-base: 51, 51, 51;

  --pst-color-h1: var(--pst-color-primary);
  --pst-color-h2: var(--pst-color-primary);
  --pst-color-h3: var(--pst-color-text-base);
  --pst-color-h4: var(--pst-color-text-base);
  --pst-color-h5: var(--pst-color-text-base);
  --pst-color-h6: var(--pst-color-text-base);
  --pst-color-paragraph: var(--pst-color-text-base);
  --pst-color-link: 0, 91, 129;
  --pst-color-link-hover: 227, 46, 0;
  --pst-color-headerlink: 198, 15, 15;
  --pst-color-headerlink-hover: 255, 255, 255;
  --pst-color-preformatted-text: 34, 34, 34;
  --pst-color-preformatted-background: 250, 250, 250;
  --pst-color-inline-code: 232, 62, 140;

  --pst-color-active-navigation: 19, 6, 84;
  --pst-color-navbar-link: 77, 77, 77;
  --pst-color-navbar-link-hover: var(--pst-color-active-navigation);
  --pst-color-navbar-link-active: var(--pst-color-active-navigation);
  --pst-color-sidebar-link: 77, 77, 77;
  --pst-color-sidebar-link-hover: var(--pst-color-active-navigation);
  --pst-color-sidebar-link-active: var(--pst-color-active-navigation);
  --pst-color-sidebar-expander-background-hover: 244, 244, 244;
  --pst-color-sidebar-caption: 77, 77, 77;
  --pst-color-toc-link: 119, 117, 122;
  --pst-color-toc-link-hover: var(--pst-color-active-navigation);
  --pst-color-toc-link-active: var(--pst-color-active-navigation);

  /*****************************************************************************
  * Icon
  **/

  /* font awesome icons*/
  --pst-icon-check-circle: "\f058";
  --pst-icon-info-circle: "\f05a";
  --pst-icon-exclamation-triangle: "\f071";
  --pst-icon-exclamation-circle: "\f06a";
  --pst-icon-times-circle: "\f057";
  --pst-icon-lightbulb: "\f0eb";

  /*****************************************************************************
  * Admonitions
  **/

  --pst-color-admonition-default: var(--pst-color-info);
  --pst-color-admonition-note: var(--pst-color-info);
  --pst-color-admonition-attention: var(--pst-color-warning);
  --pst-color-admonition-caution: var(--pst-color-warning);
  --pst-color-admonition-warning: var(--pst-color-warning);
  --pst-color-admonition-danger: var(--pst-color-danger);
  --pst-color-admonition-error: var(--pst-color-danger);
  --pst-color-admonition-hint: var(--pst-color-success);
  --pst-color-admonition-tip: var(--pst-color-success);
  --pst-color-admonition-important: var(--pst-color-success);

  --pst-icon-admonition-default: var(--pst-icon-info-circle);
  --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);

  /*****************************************************************************
  * versionmodified
  **/

  --pst-color-versionmodified-default: var(--pst-color-info);
  --pst-color-versionmodified-added: var(--pst-color-success);
  --pst-color-versionmodified-changed: var(--pst-color-warning);
  --pst-color-versionmodified-deprecated: var(--pst-color-danger);

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

Replacing/Removing Fonts#

The theme includes the FontAwesome 5 Free icon font (the .fa, .far, .fas styles, which are used for icon links and admonitions). This is the only vendored font, and otherwise the theme by default relies on available system fonts for normal body text and headers.

Attention

Previously-included fonts like Lato have been removed, preferring the most common default system fonts of the reader’s computer. This provides both better performance, and better script/glyph coverage than custom fonts, and is recommended in most cases.

The default body and header fonts can be changed as follows:

  • Using Custom CSS Stylesheets, you can specify which fonts to use for body, header and monospace text. For example, the following can be added to a custom css file:

    :root {
    --pst-font-family-base: Verdana, var(--pst-font-family-base-system);
    --pst-font-family-heading: Cambria, Georgia, Times, var(--pst-font-family-base-system);
    --pst-font-family-monospace: Courier, var(--pst-font-family-monospace-system);
}

    The -system variables are available to use as fallback to the default fonts.

  • If the font you want to specify in the section above is not generally available by default, you will additionally need to ensure the font is loaded. For example, you could download and vendor the font in the _static directory of your Sphinx site, and then update the base template to load the font resources:

    • Configure the template_path in your conf.py

    • Create a custom layout.html Jinja2 template which overloads the fonts block (example for loading the Lato font that is included in the _static/vendor directory):

      {% extends "pydata_sphinx_theme/layout.html" %}

{% block fonts %}
  <!-- add `style` or `link` tags with your CSS `@font-face` declarations here -->
  <!-- ... and optionally preload the `woff2` for snappier page loads -->
  <link rel="stylesheet" href="{{ pathto('_static/vendor/lato_latin-ext/1.44.1/index.css', 1) }}">

{% endblock %}

      To reduce the Flash of Unstyled Content, you may wish to explore various options for preloading content, specifically the binary font files. This ensure the files will be loaded before waiting for the CSS to be parsed, but should be used with care.

previous

Add/Remove items from theme sections

next

Accessibility