Skip to content

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