To use sphinx-colorschemed-images, pip install the package with:
pip install sphinx-colorschemed-images
Then modify your conf.py file and add it to your extensions setting:
extensions = [
'sphinx_colorschemed_images',
]
Now your project is ready to use the cs_image and the cs_figure directives.
The usual way to add an image to a Sphinx project is by using the image directive:
.. grid:: 2
:class-container: py-2
:gutter: 3
.. grid-item-card::
In Markdown with ``myst-parser``:
.. code-block:: markdown
```{image} img/balloon.light.png
:alt: A balloon icon
:width: 200
:align: center
```
.. grid-item-card::
Or in reStructuredText:
.. code-block:: reStructuredText
.. image:: img/balloon.light.png
:alt: A balloon icon
:align: center
:width: 200
Modern operating systems and web browsers support by default two color schemes, light and dark. But the image and figure directives produce an <img> tag with a single URI, as in the example above.
To include the dark version of the previous balloon a second image directive is required:
.. grid:: 2
:class-container: py-2
:gutter: 3
.. grid-item-card::
In Markdown with ``myst-parser``:
.. code-block:: markdown
```{image} img/balloon.dark.png
:alt: A balloon icon
:width: 200
:align: center
```
.. grid-item-card::
Or in reStructuredText:
.. code-block:: reStructuredText
.. image:: img/balloon.dark.png
:alt: A balloon icon
:align: center
:width: 200
Which produces the following <img> tag:
<img alt="A balloon icon" class="align-center"
src="_images/balloon.dark.png"
width="200">
The cs_image directive extends the functionality of the image directive by looking for two image files for the given URI, one for each color scheme. The directive generates an <img> tag with data attributes that facilitate the switch between light and dark color schemes.
The following cs_image directive:
.. grid:: 2
:class-container: py-2
:gutter: 3
.. grid-item-card::
In Markdown with ``myst-parser``:
.. code-block:: markdown
```{cs_image} img/balloon.png
:alt: A balloon icon
:width: 200
:align: center
```
.. grid-item-card::
Or in reStructuredText:
.. code-block:: reStructuredText
.. cs_image:: img/balloon.png
:alt: A balloon icon
:align: center
:width: 200
Produces the following <img> tag:
<img alt="A balloon icon" class="align-center"
data-alt-src-color-scheme-dark="_images/balloon.dark.png"
data-alt-src-color-scheme-light="_images/balloon.light.png"
src="_images/balloon.dark.png"
width="200">.. cs_image:: img/balloon.png :alt: A balloon icon :align: right :width: 200
Switch the color scheme by using the selector at the top right of the header, or change it in your operating system settings. The balloon image will switch automatically between light and dark color-schemes.
The href attribute of the anchor that wraps the <img> is also updated, so clicking on it will load the image matching the color scheme.
The cs_figure directive extends the functionality of the figure directive by looking for two image files for the given URI, one for each color scheme. The directive generates an <img> tag with data attributes that facilitate the switch between light and dark color schemes.
The following cs_figure directive:
.. grid:: 2
:class-container: py-2
:gutter: 3
.. grid-item-card::
In Markdown with ``myst-parser``:
.. code-block:: markdown
```{cs_figure} img/peace.png
:alt: An icon for peace
:width: 200
:align: right
The caption of the figure.
```
.. grid-item-card::
Or in reStructuredText:
.. code-block:: reStructuredText
.. cs_figure:: img/peace.png
:alt: An icon for peace
:align: right
:width: 200
The caption of the figure.
Produces the following <img> tag:
<figure class="align-right" id="id3">
<a class="reference internal image-reference"
href="_images/peace.light.png">
<img alt="An icon for peace"
data-alt-src-color-scheme-dark="_images/peace.dark.png"
data-alt-src-color-scheme-light="_images/peace.light.png"
src="_images/peace.dark.png" width="200">
</a>
<figcaption>
<p>
<span class="caption-text">The caption of the figure.</span>
<a class="headerlink" href="#id3" title="Link to this image">¶</a>
</p>
</figcaption>
</figure>.. cs_figure:: img/peace.png
:alt: An icon for peace
:align: right
:width: 200
The caption of the figure.
Switch the color scheme by using the selector at the top right of the header, or change it in your operating system settings. The balloon image will switch automatically between light and dark color-schemes.
The href attribute of the anchor wrapped inside the <figure> is also updated to match the image displayed. Clicking on the image in the right side should load the image that is displayed when switching color schemes.
The functionality of the extension can be customized via 4 settings:
csi_color_schemescsi_default_color_schemecsi_image_path_patterncsi_add_script_to_html_output
It defaults to ["light", "dark"].
It can be overriden, but so far web browsers can only be queried about whether the preferred color scheme is light or dark.
If you override this setting (or if your theme does), include an HTML meta tag with the color schemes:
<meta name="color-scheme" content="lightblue darkblue lightred darkred" />The JavaScript plugin included with the extension reads the meta tag to know about the available color-schemes, when they are other than the default light and dark.
It defaults to "light".
By default the URI used for the src attribute in cs_image and cs_figure directives correspond to the light version of the URI. The effect of overriding it to "dark" is that the src attribute of the <img> tag will refer to the dark color-schemed image.
This is only noticeable when the theme of your Sphinx project is not color-scheme aware (i.e: the Alabaster theme).
It defaults to "{path}/{basename}.{colorscheme}{ext}".
This setting represents the pattern that matches the URI (given in the directives cs_image and cs_figure) with files in the image directory.
It is required that the name of the color scheme, represented by the placeholder {colorscheme}, is part of the filename of the image, and not part of a directory.
Warning
The {colorscheme} placeholder can not be part of a directory name, as Sphinx copies image files to a directory named _images in the build directory, but it does not create the original directory structure.
The following two image directives will display the same file:
.. image:: img/dir1/balloon.png
:alt: A balloon icon
:align: center
:width: 200
.. image:: img/dir2/balloon.png
:alt: A balloon icon
:align: center
:width: 200Sphinx uses dir1 and dir2 to find the sources of the two files, and copies them, named identically to the destination directory _images/balloon.png. So only one of the two files survives. Only one is made available in the built _images/ directory.
Internationalized Sphinx projects usually maintain different images or figures for different languages by using the figure_language_filename [1]. In such projects you can use csi_image_path_pattern in the same way, including the {language} placeholder as part of the filename:
csi_image_path_pattern = "{path}/{basename}.{language}.{colorscheme}{ext}"It defaults to True.
When True, Sphinx will add the following HTML <script> tag to the output:
<script src="_static/sphinx-colorschemed-images.js?v=abcdefg"></script>The sphinx-colorschemed-images.js is in charge of changing between color-schemed version of images.
The npm package sphinx-colorschemed-images provides a class SphinxColorschemeImageHandler that offers the posibility to disable the automatic switching of images, leaving such control to the developer. That way, if your Sphinx theme implements color-schemes other than light and dark, you could control the transition directly with the method activate of such class.
Read the :ref:`javascript` page to see an example.
| [1] | figure_language_filename is the filename format for language-specific figures. |