Skip to content

Latest commit

 

History

History
78 lines (50 loc) · 2.69 KB

index.rst

File metadata and controls

78 lines (50 loc) · 2.69 KB

sphinx-colorschemed-images

Sphinx Color Schemed Images is an extension that makes available two new image directives to your project:

  • cs_image extends the image directive, and
  • cs_figure extends the figure directive.

These new directives add data attributes to the HTML <img> tag to help web browsers to automatically transition between light and dark color schemes. The extension adds a bit of JavaScript code to trigger an image update when the user switches the color scheme.

Quick Start

Install the package:

pip install sphinx-colorschemed-images

Modify your conf.py file and add it to your extensions setting:

extensions = [
    'sphinx_colorschemed_images',
]

Download the following files and place them in the source directory of your Sphinx project, inside the directory where you keep your images.

Let's assume your conf.py is in the docs/ directory, along with your index.rst or index.md file, and there is a docs/img/ directory where you will save the following files:

Now edit your index document and add the following cs_image directive:

.. tab-set::

    .. tab-item:: Markdown
        :sync: md

        .. code-block:: markdown

         ```{image} img/balloon.png
         :alt: A balloon icon
         :width: 200
         :align: center
         ```

    .. tab-item:: reStructuredText
        :sync: rst

        .. code-block:: reStructuredText

         .. image:: img/balloon.png
            :alt: A balloon icon
            :align: center
            :width: 200

The URI does not represent an actual filename in your directory. But it almost does. If you prefer it, use a wildcard character: img/balloon.*.

Finally, build your Sphinx project and serve it. You should see either the image for the light color scheme or the image for the dark color scheme. Switch your operating system settings and the image should update automatically.

Keep reading the :ref:`users-guide` to find out more about the extension and to see some examples.

Index

.. toctree::
   :maxdepth: 2

   users-guide
   javascript