D0020 zensical-keys¶
Rule: Zensical.toml names only keys Zensical reads.
| Code | D0020 (stable, never reused) |
| Id | zensical-keys |
| Category | book |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | deny |
Zensical ignores a key it does not know, silently; a typo in zensical.toml never fails the build |
| small-workspace | deny |
Zensical ignores a key it does not know, silently; a typo in zensical.toml never fails the build |
| medium | deny |
Zensical ignores a key it does not know, silently; a typo in zensical.toml never fails the build |
| big | deny |
Zensical ignores a key it does not know, silently; a typo in zensical.toml never fails the build |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
known |
list of strings | ["site_name", "site_dir", "docs_dir", "site_url", "site_description", "site_author", "use_directory_urls", "strict", "dev_addr", "copyright", "watch", "exclude_docs", "draft_docs", "not_in_nav", "remote_branch", "remote_name", "repo_url", "repo_name", "edit_uri_template", "edit_uri", "extra_css", "extra_templates", "extra_javascript", "nav", "validation", "validation.*", "extra", "extra.*", "markdown_extensions", "markdown_extensions.*", "plugins", "plugins.*", "theme", "theme.name", "theme.custom_dir", "theme.variant", "theme.language", "theme.direction", "theme.features", "theme.favicon", "theme.logo", "theme.font", "theme.font.text", "theme.font.code", "theme.icon", "theme.icon.logo", "theme.icon.edit", "theme.icon.view", "theme.icon.top", "theme.icon.share", "theme.icon.menu", "theme.icon.alternate", "theme.icon.search", "theme.icon.close", "theme.icon.previous", "theme.icon.next", "theme.icon.repo", "theme.icon.annotation", "theme.icon.tag", "theme.icon.admonition", "theme.icon.admonition.*", "theme.icon.blog", "theme.icon.blog.back", "theme.icon.blog.date", "theme.icon.blog.date_updated", "theme.icon.blog.categories", "theme.icon.blog.readtime", "theme.palette", "theme.palette.media", "theme.palette.scheme", "theme.palette.primary", "theme.palette.accent", "theme.palette.toggle", "theme.palette.toggle.icon", "theme.palette.toggle.name"] |
dotted key paths zensical.toml may use, read from Zensical's own configuration code; a path ending .* accepts any key below it (a plugin's options, a reader-chosen admonition icon map) |
Why¶
Zensical reads zensical.toml key by key, applying its own defaults for the keys it knows and never looking at the rest: a key it does not recognize is neither used nor reported. sitename instead of site_name, theme.customdir instead of theme.custom_dir, a plugin option moved up a level by accident: the build still says "No issues found", and the setting the author meant to apply never takes effect, even with strict = true. A book Zensical builds from a legacy MkDocs project reads mkdocs.yml instead, unchanged: the same keys, the same silent typo.
The lint walks the table Zensical reads ([project] when zensical.toml nests that way, mkdocs.yml's document root, or the TOML file's own root when it has no [project]) and flags a key that is not one of known's dotted paths (site_name, theme.custom_dir, ...). A path ending .* accepts any key below it: extra, plugins, markdown_extensions and a theme's admonition icon map are free-form, so their contents are not checked. A list of named variants (theme.palette, written as a TOML array of tables or a YAML list) is checked the same way, one entry at a time; nav's list is not, since its keys are reader-chosen page titles.
How to fix¶
Correct the key, or drop it. A key Zensical does not read yet, or one from a theme or plugin this list does not cover: add its dotted path to known (site_name, theme.favicon, plugins.* for a whole plugin's options).
Configure¶
[lints.zensical-keys]
level = "deny"
known = ["site_name", "site_dir", "docs_dir", "site_url", "site_description", "site_author", "use_directory_urls", "strict", "dev_addr", "copyright", "watch", "exclude_docs", "draft_docs", "not_in_nav", "remote_branch", "remote_name", "repo_url", "repo_name", "edit_uri_template", "edit_uri", "extra_css", "extra_templates", "extra_javascript", "nav", "validation", "validation.*", "extra", "extra.*", "markdown_extensions", "markdown_extensions.*", "plugins", "plugins.*", "theme", "theme.name", "theme.custom_dir", "theme.variant", "theme.language", "theme.direction", "theme.features", "theme.favicon", "theme.logo", "theme.font", "theme.font.text", "theme.font.code", "theme.icon", "theme.icon.logo", "theme.icon.edit", "theme.icon.view", "theme.icon.top", "theme.icon.share", "theme.icon.menu", "theme.icon.alternate", "theme.icon.search", "theme.icon.close", "theme.icon.previous", "theme.icon.next", "theme.icon.repo", "theme.icon.annotation", "theme.icon.tag", "theme.icon.admonition", "theme.icon.admonition.*", "theme.icon.blog", "theme.icon.blog.back", "theme.icon.blog.date", "theme.icon.blog.date_updated", "theme.icon.blog.categories", "theme.icon.blog.readtime", "theme.palette", "theme.palette.media", "theme.palette.scheme", "theme.palette.primary", "theme.palette.accent", "theme.palette.toggle", "theme.palette.toggle.icon", "theme.palette.toggle.name"]
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(zensical-keys) <reason> (waivers); the code works there too, as in [lints.D0020].