multiple color themes? dark theme?

[mgeier]

The mdBook project has a mechanism to select a color theme, see e.g. https://rust-lang.github.io/mdBook/.

It would be great to have a similar (of course optional) mechanism for the insipid theme.

I think the main difference to overcome is the code syntax highlighting. mdBook uses a JavaScript based solution (https://highlightjs.org/ if I'm not mistaken), while Sphinx uses https://pygments.org/ to generate the necessary CSS styles during the build process (without using JavaScript).

By default, Sphinx generates only one set of highlighting styles, but we would somehow have to generate multiple styles with Pygments, I guess.
This might need some Sphinx extension code, which would go kinda against my "back to the basics" goal mentioned in https://insipid-sphinx-theme.readthedocs.io/intro.html#goals. Therefore, I think it would be great to make the whole thing optional.

I recently discovered the Sphinx setting pygments_dark_style, which could be interesting (or not?), see https://www.sphinx-doc.org/en/master/development/theming.html#creating-themes.
See also sphinx-doc/sphinx#7101 and sphinx-doc/sphinx#7142.

The furo theme uses this uses something else which is confusingly also called pygments_dark_style (pradyunsg/furo#13, see also pradyunsg/furo#24).

Potential default dark styles for Pygments: monokai, native, inkpot (except for ugly highlighted lines), zenburn.
See also pygments/pygments#1526 for problems with tracebacks.

A Sphinx extension that adds a dark mode to the RTD theme: https://github.com/MrDogeBro/sphinx_rtd_dark_mode

Another site with support for dark mode: https://pillow.readthedocs.io/ (python-pillow/Pillow#4968)

And another one: https://docs.godotengine.org/en/stable/index.html

And another one: https://fasterthanli.me/

Another: https://rome.tools/blog/2022/02/08/rome-formatter-and-rust-update

And more:

https://arstechnica.com/

https://www.c82.net/math-instruments/

A MkDocs theme with light/dark switch: https://squidfunk.github.io/mkdocs-material/getting-started/

I've also found an interesting Sphinx-based project which has a dark-theme-selector: https://proplot.readthedocs.io/.

Docusaurus also has a light/dark switch, e.g.

• https://oxidizer-rs.github.io/
• https://www.dimforge.com/
• https://tauri.studio/docs/getting-started/prerequisites

Discussions about dark mode (and draft implementation) for Python theme:
python/python-docs-theme#43
python/python-docs-theme#44
https://septatrix.github.io/cpython-dark-docs/

Discussions about sphinx_rtd_theme: readthedocs/sphinx_rtd_theme#224

pydata-sphinx-theme: pydata/pydata-sphinx-theme#273, pydata/pydata-sphinx-theme#458

CSS-only dark mode: https://dev.to/kleinfreund/css-only-dark-mode-3eg8

Pure CSS switcher: https://codepen.io/demilad/pen/bZRjpb

https://github.com/GoogleChromeLabs/dark-mode-toggle

https://paulmillr.com/posts/using-dark-mode-in-css/

https://alexandersandberg.com/articles/creating-a-website-theme-switcher-with-css-only/

More switcher examples: https://snarky.ca/, https://docs.soliditylang.org/

An overview article: https://css-tricks.com/a-complete-guide-to-dark-mode-on-the-web/

Another approach: https://chrismorgan.info/blog/dark-theme-implementation/

Any further suggestions?

Any volunteers?

[pradyunsg]

I recently discovered the Sphinx setting pygments_dark_style, which could be interesting (or not?)

This is Furo-specific. Furo's dark mode support is honestly a horrible layer of hacks, that just so happen to be a stable set of hacks thanks to the amazing stability of Sphinx.

https://github.com/pradyunsg/furo/blob/32b2fe5709c1d30cef981f936ce9592d0758bec0/src/furo/__init__.py#L327

[mgeier]

Thanks for checking this out!

This is Furo-specific.

There is definitely something in Sphinx that's called pygments_dark_style:

https://github.com/sphinx-doc/sphinx/search?q=pygments_dark_style

But maybe the one from Furo is a different thing with the same name?

I just assumed it would be the same thing ...

I don't know if that's possible, but I would like to be able to have a dark mode without needing any theme-specific Python code.
And maybe it might even work without JavaScript ...?

[pradyunsg]

But maybe the one from Furo is a different thing with the same name?

It is.

https://github.com/sphinx-doc/sphinx/blob/2be06309518d9401a42880bb5b4321dfdd1e5e90/sphinx/builders/html/__init__.py#L288-L292

Furo uses a completely different selector for the CSS and places all the styles into a single file. Sphinx uses multiple files, and puts the dark stuff under a separate CSS file that's activated with a media query; something that completely breaks the moment if the two pygments themes have any rule that isn't overlapping. :)