Skip to content

D0019 theme-feature-conflicts

Rule: Theme features that exclude each other are not both on.

Code D0019 (stable, never reused)
Id theme-feature-conflicts
Category book
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small deny Zensical does not support the conflicting features together, and builds neither error nor warn about it
small-workspace deny Zensical does not support the conflicting features together, and builds neither error nor warn about it
medium deny Zensical does not support the conflicting features together, and builds neither error nor warn about it
big deny Zensical does not support the conflicting features together, and builds neither error nor warn about it
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
pairs list of strings ["navigation.prune, navigation.expand", "navigation.indexes, toc.integrate"] theme features Zensical does not support together, each entry "a, b"
needs-site-url list of strings ["navigation.instant"] theme features that need project.site_url set, since they rely on the generated sitemap.xml

Why

Zensical's theme features are flags in project.theme.features, and some of them do not work together: navigation.prune strips the navigation down to what is visible, which navigation.expand needs in full; navigation.indexes and toc.integrate both want the same space in the sidebar. A project that turns both flags of a pair on gets no error from zensical build, only a theme that silently drops or garbles one of them.

navigation.instant (and the instant-navigation flags built on it) reads the site's sitemap.xml to know what to fetch. Without project.site_url set, Zensical builds an empty sitemap, and instant navigation never finds a page to load.

How to fix

Keep only one feature of a conflicting pair in project.theme.features. For a feature in needs-site-url, set project.site_url to the book's published URL.

Configure

[lints.theme-feature-conflicts]
level = "deny"
pairs = ["navigation.prune, navigation.expand", "navigation.indexes, toc.integrate"]
needs-site-url = ["navigation.instant"]
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(theme-feature-conflicts) <reason> (waivers); the code works there too, as in [lints.D0019].