docs: explain syntax highlighting workaround (#1853)

Explain what you have to do to add different color schemes for syntax
highlighting,
originally explained in #1727.

docs/_redirects

@@ -4,5 +4,8 @@
 /how-to/use    /how-to/configure
 /how-to/update /about
 /how-to/using  /
+/how-to/customize/add-custom-css       /how-to/customize/css
+/how-to/customize/add-custom-css       /how-to/customize/js
+/how-to/customize/add-custom-templates /how-to/customize/templates
 /demo/admonitions /demo/notes
 /demo/code     /demo/code-blocks

docs/how-to/customize/includes/color-scheme-different.rst

@@ -0,0 +1,25 @@
+Select different color schemes for light and dark modes
+-------------------------------------------------------
+
+If you want to use different color schemes for syntax highlighting in light and dark mode,
+follow these steps:
+
+#. Select a theme you want to use in light mode and :ref:`set it as your color scheme <sec:set-color-scheme>` with the ``pygments_style`` option.
+#. Select a color scheme you want to use in dark mode and run the following command:
+
+   .. code-block:: sh
+      :emphasize-text: THEME
+
+      pygmentize -s THEME -f html -a .dark > pygments-dark.css
+
+   This runs the ``pygmentize`` command, which is part of the Pygments package.
+   If you installed the |product|, Pygments is also installed.
+
+#. Add the file :file:`pygments-dark.css` as :ref:`custom css <sec:custom-css>`.
+
+.. dropdown:: More information
+
+   Themes can define ``pygments_style`` and ``pygments_style_dark`` options in their :file:`themes.conf` file.
+   This applies different color schemes in light and dark mode based on the system settings and the ``prefers-color-scheme`` media query.
+   However, this doesn't work with manual theme switchers that select different CSS based on classes.
+   Therefore, we have to add the styles for dark mode as custom CSS.

docs/how-to/customize/includes/color-scheme-same.rst

@@ -0,0 +1,20 @@
+.. _sec:set-color-scheme:
+
+Select color schemes for syntax highlighting
+--------------------------------------------
+
+Syntax highlighting is provided by the Pygments library and the *bw* color scheme.
+To select a different color scheme **for both light and dark mode**,
+use the :confval:`sphinx:pygments_style` option:
+
+.. code-block:: python
+   :caption: |conf|
+   :emphasize-text: PYGMENTS_THEME
+
+   pygments_style = "PYGMENTS_THEME"
+
+For a list of available themes, see the Pygments_ documentation.
+For even more themes, see the `accessible pygments themes`_ project.
+
+.. _Pygments: https://pygments.org/styles/
+.. _accessible pygments themes: https://github.com/Quansight-Labs/accessible-pygments

docs/how-to/customize/index.rst

@@ -15,6 +15,7 @@ Customize the theme
 .. toctree::
    :caption: In this section
 
-   add-custom-css
-   add-custom-js
-   add-custom-templates
+   syntax-highlighting
+   css
+   js
+   templates

docs/how-to/customize/syntax-highlighting.rst

@@ -0,0 +1,20 @@
+.. meta::
+   :description: Select syntax highlighting color schemes.
+   :twitter:description: Select syntax highlighting color schemes.
+
+Syntax highlighting
+===================
+
+.. rst-class:: lead
+
+   Select different color schemes for syntax highlighting in code blocks.
+
+.. tip::
+
+   When selecting different color schemes,
+   make sure that it works in all situations with sufficient contrast,
+   for example, with line highlighting or with captions.
+   Check the background colors and code block borders for overlaps.
+
+.. include:: includes/color-scheme-same.rst
+.. include:: includes/color-scheme-different.rst