This is a proposal for re-organising the way that theme works.

current situation

IkiWiki sites reference two stylesheets: style.css, which is either the base "anti-theme" CSS or, if a theme is configured, that theme's CSS concatenated to the anti-theme; local.css which defaults to empty, is controlled by the user/site source and can override the former.

IkiWiki's build process constructs the concatenated theme CSS files at IKiWiki-build time, and IkiWiki distributions ship the concatenated files.

meta has some support for adding further stylesheets to a site, but it's broken (see meta plugin should not add alternate stylesheets and title by default).

The exemplar demonstration IkiWiki site, https://ikiwiki.info, deliberately does not configure a theme. The documentation has some thumbnails of the theme choices which are very small, by modern standards, at themes. Users do not get a great idea of what a theme looks like.

proposal

Either remove the additional stylesheet functionality from meta completely, or re-work it as proposed to not use "alternate". I'm leaning towards the former because I can't see a need for adding a stylesheet via meta that isn't addressed by support for local.css.

Do not concatenate the base style and theme styles in IkiWiki build. The theme stylesheets should be shipped in their source form. This is a minor simplification to the build.

Adjust theme so that the selected theme is added to page.tmpl as a third stylesheet, in between style and local.

Extend theme to support configuring a list of alternate themes. The named themes will be included into site builds and into page sources as "alternate stylesheets". Users can then select an alternate theme for such sites (Firefox has built in UI for this, I don't know about other browsers). E.g.

theme: actiontabs
alternate_themes:
- goldtype
- monochrome

Reconfigure https://ikiwiki.info to name all shipped themes as alternate styles. This preserves the choice to have the default style the "anti-theme", but also gives us a way of demoing all the themes for users.

drawbacks

Having three separate CSS files referenced in page HTML is three separate HTTP requests to build the page. However, the current situation is already two. For those who are concerned with optimising sites, we probably need to implement a more sophisticated optimiser plugin, which could flatten multiple stylesheets down to one, and potentially perform other changes (minification if there's any point, remove overridden or unused styles, etc.)

We may want to provide a way for users to specify a site-local preference for dark or light mode, independent of their browser or OS setting. This could be done by using "alternate stylesheets" (I do this on https://jmtd.net), but using that mechanism for both theme choices and dark/light mode per-theme would result in a long list.

— Jon, 2026-09-05