Image and Iframe Dark Mode Colour Inverter

Image and Iframe Dark Mode Colour Inverter#

The Sphinx-Image-Inverter extension automatically adapts figures, images, and iframes to dark mode by inverting their colours. Meanwhile, it makes sure that a colour is still recognizable, i.e. red stays red, blue stays blue, etc. This ensures that visuals remain readable and consistent across light and dark themes. In this exercise, you’ll install the extension, configure its options, and experiment with enabling and disabling inversion for specific images.

Configure image inversion#

You can control how and when images are inverted by adjusting parameters in _config.yml.

  1. To disable inversion globally, set inverter_all to false. This disables automatic inversion for all images. This is especially useful if your images are photos which won’t look good when inverted.

    sphinx:
  config:
    inverter_all: false

  2. To enable inversion globally, set inverter_all to true. This enables automatic inversion for all images. This is useful if your images are mostly diagrams or plots which benefit from inversion.

    sphinx:
  config:
    inverter_all: true

  3. If you would like to selectively include or exclude specific figures or iframes from inversion the dark-light class can be used. Locate the markdown file that contains the image you want to exclude from inversion and add the :class: dark-light attribute as follows:

    ```{figure} images/example_plot.png
:class: dark-light
:width: 400
```

    Note

    When dark mode is toggled, this image will not be inverted if inverter_all: true.
    If inverter_all: false, only this image will be inverted.

  4. The saturation can also be adjusted. The default colour saturation is 1.5. Let us reduce the contrast by changing this to 1.0:

    sphinx:
  config:
    inverter_saturation: 1.0

    Tip

    Try different saturation levels to see how they affect contrast in dark mode — between 1.0 (no change) and 2.0 (vivid colours) is recommended.

  5. It is also possible to choose to show or hide text depending on the selected theme. This is useful for adding hints or notes that depend on visibility. Try this out using the following classes:

    <span class="only-light">This message is only visible in light mode.</span>

<span class="only-dark">This message appears only in dark mode.</span>

  6. When you are ready, commit your changes to the repository by clicking on the green Commit changes button.

  7. Add a commit message.

  8. To see your changes, go to Actions - The most recent workflow run overview.md / the commit message of the commit you just made - Wait for it to finish - In the summary, click on the link of your book shown in the table Branches deployed and under Primary book at root (getting bored of waiting? There’ll be exercising on doing this locally which prevents you from waiting).

  9. Do you see your change? If you don’t see it click CTRL+F5/Control+F5to refresh the page.

Check your understanding

Before moving on, make sure you can answer:

  • What does the Sphinx-Image-Inverter extension do?

  • How do you disable automatic inversion for all images?

  • What is the effect of the dark-light class?

  • What happens when you change the inverter_saturation value?

Contents