Configuration

A Zensical project is configured by one file at the project root, normally zensical.toml, which zensical new generates with commented examples (see Installation and CLI). Zensical can also read an existing mkdocs.yml, which makes migration gradual: the same project builds with either mkdocs build or zensical build (see Migrating from Material for MkDocs).

The two formats describe the same settings. The official configuration reference shows every setting twice, once for zensical.toml and once for mkdocs.yml, and recommends the mkdocs.yml form while a project must keep working with both builders. This page does the same.

Every setting of zensical.toml currently lives in a single table declared on the first line:

The documentation says that further tables may be introduced later and that settings may then move out of [project], with automatic refactorings promised so that no manual migration is needed. Nested settings use dotted tables such as [project.theme], [project.extra] or [project.plugins.mkdocstrings.handlers.python].

The settings below are the ones the basics page of the configuration reference lists. Each row gives the TOML key, the mkdocs.yml key, and what the setting does.

Other keys appear in the file that zensical new writes, for instance nav, repo_url, repo_name, edit_uri, extra_css, extra_javascript and the [project.theme] table. They are covered on their own pages: Navigation, Theming and Customization and Blog, Tags and Plugins.

The translation from mkdocs.yml to zensical.toml is mechanical, but a few shapes differ:

The two files below configure the same Pocket Units site:

Source: Zensical docs: Basics

Both files built the same four pages with zensical build:

Required and unknown keys behave as follows in 0.0.72:

site_url is the canonical URL of the published site. Zensical writes it into the HTML head as the canonical link, uses it to build the absolute URLs of the sitemap, and uses its path as the base path of the preview server. The documentation says to set it unless you build for offline use.

Source: Zensical docs: Basics

With that value, the build of guides/convert.md produced a canonical link of https://example.org/pocket-units/guides/convert/ and a sitemap.xml whose <loc> entries all start with https://example.org/pocket-units/. Two consequences are worth knowing:

When use_directory_urls is false, which Zensical also sets automatically when building for offline use, the canonical link ends in the file name (.../guides/convert.html) and the pages are written as convert.html instead of convert/index.html.

docs_dir is the directory with the source Markdown files and assets, and site_dir is where the generated site is written. Both must be relative paths and are resolved relative to the configuration file, not the current directory.

Source: Zensical docs: Basics

In the test run:

The official reference states that docs_dir cannot be set to . (a temporary limitation, with the advice to keep the sources in a subdirectory such as docs). Version 0.0.72 did build with docs_dir = ".", but it then treated the whole project as documentation: the configuration files, the Python package and previous output were copied into the site directory. Treat that as unsupported behaviour and keep a dedicated directory.

Keep site_dir out of docs_dir, and add it to .gitignore. A leftover generated site inside the source tree would be processed as content. If output looks stale after an upgrade, zensical build --clean clears the cache.

exclude_docs, draft_docs and not_in_nav select files with the same pattern syntax. The value must be a single string with one pattern per line; a TOML array is rejected with Error: 'exclude_docs' must be a multiline string. Patterns follow .gitignore rules and are resolved relative to docs_dir:

Source: Zensical docs: Basics, File patterns

Patterns are evaluated in order and the last matching pattern decides. Negation only works inside one setting: an exclude_docs match cannot be reversed by a negated not_in_nav pattern. The patterns apply to Markdown pages and also to other files in docs_dir, such as images, which is how assets used only by drafts can be kept out of the build.

The test tree used for the next sections is:

The matrix summarises the three settings: a page matched by exclude_docs disappears everywhere, a draft is only dropped from the built site, and a page in not_in_nav is kept everywhere except the automatic navigation.

exclude_docs removes files from both zensical build and zensical serve. A page matched here cannot be opened, is not searched and is not in the sitemap.

Source: Zensical docs: Basics

The build wrote index.html, guides/convert/index.html and internal/changelog/index.html (plus 404.html), and neither private/plans/ nor scratch.tmp existed in public/. During zensical serve, a request for /private/plans/ answered HTTP 404.

Three kinds of file are excluded by default, before your patterns are applied: dotfiles, files inside dot directories, and the top-level templates/ directory. Reverse a default with !:

Source: Zensical docs: Basics

With !.* added, .hidden.md was built to public/.hidden/index.html. Use this for files such as a .well-known folder, and remember that dot directories you do not want published (for example .git copies or editor folders) are then no longer protected.

Because the pattern list is replaced rather than extended, every path that must stay hidden has to remain listed.

draft_docs marks work in progress. Matched files are left out of zensical build but included in zensical serve, so authors can preview them while the published site stays clean. No files are drafts by default.

Source: Zensical docs: Basics

Observed behaviour:

A file matched by both exclude_docs and draft_docs is excluded, as the next section explains.

not_in_nav omits pages from the automatically generated navigation while still building them. Such pages stay in search results and in the sitemap, which makes the setting suitable for changelogs, legal pages or landing pages that are reached by direct links.

Source: Zensical docs: Basics

In the test run, internal/changelog/index.html was built, appeared in search.json and sitemap.xml, and was absent from the navigation of index.html. Two limits are documented: a matched page can still be added to an explicit nav by name, and the setting is not applied to navigation generated by the awesome-nav plugin.

The remaining settings of the basics page are short:

Source: Zensical docs: Basics

This file built without issues; the page canonical link then ended in guides/convert.html. The dev_addr and library_version values are only observable through the preview server and a template, which this run did not check.