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].