100% plant-based blog.

Dark theme for Zeal Docs

Zeal (AUR/zealdocs) is a good software document browser, but by default is it mostly black on white, which can be uncomfortable for those who use dark background colors for the rest of their system. I'll describe the officially supported way first, and then what I consider to be a better workaround (requires picom, available for Arch as either community/picom or AUR/picom-git).

Officially Supported Dark Theming

Zeal (aur/zeal) does in fact support dark theming. To enable it, you need the line dark_mode=true in your ~/.config/Zeal/Zeal.conf, under [content]. This however, only makes the pages themselves dark, but leaves the (relatively large) Qt UI elements in the app light. There is additionally the custom_css_file= option (similarly under [content]), that allows you to load a dark Qt css/qss stylesheet for the UI elements. You could use for instance qdarkstyle.

Note: Make sure to close the Zeal application (also from tray) before editing settings, else they will be overwritten.

Downsides

Aside from some minor issues like Zeal not loading the custom css file (except when passed as a CLI argument), the biggest downside is that while using dark theme, Zeal/Qt will still always first load the default white sheet, and only then your dark sheet. This causes your Zeal window to effectively flash white on certain content changes, which can be pretty uncomfortable and renders some of the advantages of dark theming your applications moot.

The Better Way

So instead, we can use picom's invert-color-include setting to what, in this case, ends up being a pretty decent dark theme for Zeal. You simply have to add the following lines to your ~/.config/picom.conf (or the deprecated ~/.config/compton.conf, if you are still using that):

invert-color-include = [
    "class_g = 'Zeal'"
    ];

And voilà! Zeal, both the doc pages and the UI elements, are now dark. I tried switching the docsets and at least on my hardware the inversion was fast enough to not see flashes of white, rendering the dark theme experience better than that of the officially supported method.

Limitations

Of course this is indeed a simple workaround (that requires a relatively CPU costly program to work) and does not support, for instance, any configuration of the theme. A small tweak you could do is, once again in picom, add some minor transparency to soften the colors:

opacity-rule = [
    "90:class_g = 'Zeal'",
];

But given that you are looking at text on what is possibly a floating window on top of more text, this starts to look messy very quickly.

You could of course use this method in conjuction with loading a custom css theme, but that would be a monumental operation, especially given that you'd have to think in inverse colors. However, I find the end result to be Good Enough(tm).