=======================
Theme variables and CSS
=======================

.. _pydata-css-variables: https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/
.. _css-variable-help: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties

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:

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``

   .. code-block:: python

       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 <css-variable-help_>`_ that can be
used to quickly control behavior and display across your documentation.

These are based on top of the basic `Bootstrap CSS variables <https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables>`_
extended with some theme specific variables.

base variables
--------------

In order to change a variable, follow these steps:

1. :ref:`Add a custom CSS stylesheet <custom-css>`. 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``:

   .. code-block:: css

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

.. important::

   Note that these are `CSS variables <css-variable-help_>`_ and not
   `SASS variables <https://sass-lang.com/documentation/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 <pydata-css-variables_>`_:

.. literalinclude:: ../../src/pydata_sphinx_theme/assets/styles/variables/_layout.scss
  :language: scss

.. literalinclude:: ../../src/pydata_sphinx_theme/assets/styles/variables/_fonts.scss
  :language: scss

.. literalinclude:: ../../src/pydata_sphinx_theme/assets/styles/variables/_icons.scss
  :language: scss

.. literalinclude:: ../../src/pydata_sphinx_theme/assets/styles/variables/_admonitions.scss
  :language: scss

.. literalinclude:: ../../src/pydata_sphinx_theme/assets/styles/variables/_versionmodified.scss
  :language: scss

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).

.. raw:: html

    <style>
      span.pst-badge {border: 1px solid var(--pst-color-text-base);}
      span.pst-primary {background-color: var(--pst-color-primary);}
      span.pst-secondary {background-color: var(--pst-color-secondary);}
      span.pst-success {background-color: var(--pst-color-success);}
      span.pst-info {background-color: var(--pst-color-info);}
      span.pst-warning {background-color: var(--pst-color-warning);}
      span.pst-danger {background-color: var(--pst-color-danger);}
      span.pst-background {background-color: var(--pst-color-background);}
      span.pst-on-background {background-color: var(--pst-color-on-background);}
      span.pst-surface {background-color: var(--pst-color-surface);}
      span.pst-on-surface {background-color: var(--pst-color-on-surface);}
      span.pst-target {background-color: var(--pst-color-target);}
    </style>

    <p>
      <span class="sd-sphinx-override sd-badge pst-badge pst-primary">primary</span>
      <span class="sd-sphinx-override sd-badge pst-badge pst-secondary">secondary</span>
      <span class="sd-sphinx-override sd-badge pst-badge pst-success">success</span>
      <span class="sd-sphinx-override sd-badge pst-badge pst-info">info</span>
      <span class="sd-sphinx-override sd-badge pst-badge pst-warning">warning</span>
      <span class="sd-sphinx-override sd-badge pst-badge pst-danger">danger</span>
      <span class="sd-sphinx-override sd-badge pst-badge pst-background">background</span>
      <span class="sd-sphinx-override sd-badge pst-badge pst-on-background">on-background</span>
      <span class="sd-sphinx-override sd-badge pst-badge pst-surface">surface</span>
      <span class="sd-sphinx-override sd-badge pst-badge pst-on-surface">on-surface</span>
      <span class="sd-sphinx-override sd-badge pst-badge pst-target">target</span>
    </p>


**To modify the colors for these variables** for light and dark themes, :ref:`add a custom CSS stylesheet <custom-css>` with a structure like so:

.. code-block:: css

    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.

- :code:`background`: color of the back-most surface of the documentation
- :code:`on-background` elements that are set on top of this background (e.g. the header navbar on dark mode).
- :code:`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).
- :code:`on-surface` elements that are on top of :code:`surface` elements (e.g. sidebar directives).

The following image should help you understand these overlays:

.. raw:: html

    <style>
      /* use https://unminify.com to check the indented version of the overlay component */
      .overlay-container {margin-top: 10%; left: 20%; --width: 80%; --height: 200px; width: var(--width); height: var(--height); position: relative;}
      .overlay-container .pst-overlay {position: absolute; border: 2px solid var(--pst-color-border);}
      .overlay-container .pst-background {background-color: var(--pst-color-background); width: var(--width); transform: skew(-45deg); height: var(--height);}
      .overlay-container .pst-on-background {background-color: var(--pst-color-on-background); height: var(--height); width: calc(var(--width) / 3); transform: skew(-45deg) translate(-2rem, -2rem);}
      .overlay-container .pst-surface {background-color: var(--pst-color-surface); height: var(--height); width: calc(var(--width) / 3); transform: skew(-45deg) translate(-2rem, -2rem); left: calc(var(--width) / 3 * 2);}
      .overlay-container .pst-on-surface {background-color: var(--pst-color-on-surface); width: calc(var(--width) / 3); height: calc(var(--height) * 0.66); transform: skew(-45deg) translate(-2rem, -4rem); left: calc(var(--width) / 3 * 2);}
      .overlay-container .label {position: absolute; bottom: 0.5rem; left: 50%; transform: skew(45deg) translateX(-50%); white-space: nowrap;}
    </style>

    <div class="overlay-container">
      <div class="pst-overlay pst-background">
        <p class="label">background</p>
      </div>
      <div class="pst-overlay pst-on-background">
        <p class="label">on-background</p>
      </div>
      <div class="pst-overlay pst-surface">
        <p class="label">surface</p>
      </div>
      <div class="pst-overlay pst-on-surface">
        <p class="label">on-surface</p>
      </div>
    </div>

.. it would be nice to have this `.. literalinclude::` here to actually show
   the file, but there's a pygments bug that fails to lex SCSS variables
   (specifically the `$` symbol that prepends SCSS variables, see
   https://github.com/pygments/pygments/issues/2130). So for now it's
   just a raw download link.

For a complete list of the theme colors that you may override, see the :download:`PyData theme CSS colors stylesheet <../../src/pydata_sphinx_theme/assets/styles/variables/_color.scss>`.

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 <https://help.farbox.com/pygments.html>`__.

.. code-block:: python

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

.. danger::

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