Skip to content

Basics

A Zensical project is configured via a zensical.toml file. If you create your project using the new command, this file will be automatically created for you, and include an example configuration with comments describing the available settings.

The project scope

A zensical.toml configuration begins with a line declaring a scope for the project:

[project]

As of now, all settings are contained within this scope. As we evolve Zensical, we will introduce additional scopes and move settings out of the project scope where appropriate. Of course, we'll provide automatic refactorings, so there's no need for manual migration.

Settings

site_name

The site_name is a required setting that provides the name of the site to be included in the HTML head and in the page headers.

[project]
site_name = "My Zensical project"

site_name: My Zensical project

site_url

The site_url specifies the canonical URL for the site, which appears in the HTML header and should be set unless you're building for offline usage.

[project]
site_url = "https://example.com"

site_url: https://example.com

site_description

A site_description is used in the HTML head if the page itself does not specify a description in the page metadata. Some search engines use this to describe the page content.

[project]
site_description = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."

site_description: Lorem ipsum dolor sit amet, consectetur adipiscing elit.

site_author

The site_author setting is used in the HTML head element to indicate the author of a website.

[project]
site_author = "John Doe"

site_author: John Doe

The copyright setting allows you to specify a copyright notice that will be inserted into the footer of your pages. You can specify an HTML fragment here or just plain text.

[project]
copyright = "© 2025 Jane Doe"

copyright: "© 2025 Jane Doe"

docs_dir

The docs_dir setting specifies the path to the directory that contains your source files. This must be a relative path, which is resolved relative to the configuration file.

[project]
docs_dir = "docs"

docs_dir: docs

docs_dir can't be set to .

This is a temporary limitation. We're working on increasing flexibility. As a workaround, please set docs_dir to a subdirectory, such as docs, and move your source files there. You can subscribe to the backlog item for this feature if you want to be notified when it's available.

site_dir

The site_dir specifies the path to the directory your site will be written to. This must be a relative path, which is resolved relative to the configuration file.

[project]
site_dir = "site"

site_dir: site

extra

The extra configuration option serves as a way to store arbitrary key-value pairs that are used by templates. If you override templates, you can use these values to customize behavior.

[project.extra]
key = "value"

extra:
  key: value

use_directory_urls

The use_directory_urls setting controls the directory structure of your documentation site, and thereby the URL format used for linking to pages.

[project]
use_directory_urls = false

use_directory_urls: false

Note that this is automatically set to false when building for offline usage, so your documentation can be browsed from a local filesystem without a web server. The default value is true.

Source file Generated File URL Format
index.md index.html /
usage.md usage.html /usage/
about/license.md about/license.html /about/license/
Source file Generated File URL Format
index.md index.html /index.html
usage.md usage.html /usage.html
about/license.md about/license.html /about/license.html

exclude_docs

Files matched by exclude_docs are excluded from both zensical build and zensical serve. File pattern syntax is supported. The patterns are applied to Markdown pages and other files within docs_dir, including images and other assets.

[project]
exclude_docs = """
/private/
*.tmp
"""

exclude_docs: |
  /private/
  *.tmp

Dotfiles, files inside dot directories, and the top-level templates/ directory are excluded by default. These default patterns are applied before the configured patterns. Default exclusions can be reversed with !:

[project]
exclude_docs = """
!.*
!/templates/
"""

exclude_docs: |
  !.*
  !/templates/

Files matched by exclude_docs are excluded even when matched by draft_docs or not_in_nav.

draft_docs

Files matched by draft_docs are excluded from zensical build but included during zensical serve. File pattern syntax is supported. No files are marked as drafts by default.

[project]
draft_docs = """
/drafts/
*.draft.md
"""

draft_docs: |
  /drafts/
  *.draft.md

During preview, a draft notice is added to draft pages. Draft pages are omitted from the default, automatically generated navigation, even during preview. They can be opened by URL or added to an explicit nav for preview.

Patterns are also applied to assets within docs_dir. Assets required only by draft pages can be matched by draft_docs to exclude them from builds.

not_in_nav

Pages matched by not_in_nav are omitted from the default, automatically generated navigation. These pages are still built and included in search and the sitemap. File pattern syntax is supported. No pages are omitted by this setting by default.

[project]
not_in_nav = """
/internal/
changelog.md
"""

not_in_nav: |
  /internal/
  changelog.md

Matched pages can still be included in an explicit nav. The setting is not applied to navigation generated by awesome-nav.

dev_addr

When running zensical serve, the built-in web server binds to this address to serve your documentation site locally. Note that you need to specify an IP address and a port.

[project]
dev_addr = "localhost:3000"

dev_addr: localhost:3000

The default dev_addr is localhost:8000.

watch

Additional file or directory paths to be monitored for changes during preview. Each entry is a string resolved relative to the directory containing the configuration file. When a watched path is modified, a full rebuild is triggered.

The following paths are already watched automatically, without explicit configuration:

  • All files within docs_dir
  • Theme files (installed themes and custom themes)
  • Files from the base_path and auto_append options of the Snippets extension (pymdownx.snippets)
  • Files from the module, modules, include_yaml, include_dir options of the Macros extension (zensical.extensions.macros)
  • Files from the paths option of the mkdocstrings compatibility extension

Symbolic links

Zensical follows symbolic links only when their targets are inside a watched directory. This prevents a project from accessing files outside the paths it is configured to monitor. To use a target elsewhere, add its containing directory to watch. Support for targets outside watched directories is tracked in our backlog.

[project]
watch = [
  "data.csv",
  "fragments",
]

watch:
  - data.csv
  - fragments

File patterns

The exclude_docs, draft_docs, and not_in_nav settings must be configured as strings, with one pattern per line. .gitignore syntax is supported, and paths are resolved relative to docs_dir:

  • A leading / is used to anchor a pattern to docs_dir: only /private.md at the root is matched.
  • A name without / is matched at any depth: guides/private.md is also matched by private.md.
  • A trailing / is used to match a directory and its contents: draft directories at any depth are matched by drafts/.
  • Wildcards are supported: Markdown files are matched by *.md, and Markdown files throughout guides/ are matched by guides/**/*.md.
  • A leading ! is used to reverse a previous match: drafts/keep.md is restored by !drafts/keep.md after drafts/.
  • Blank lines and lines beginning with # are ignored. A literal leading # or ! must be escaped with \.

Patterns are evaluated in order, and the last matching pattern is used. Negation is applied only within the same setting. For example, an exclude_docs match cannot be reversed by a negated not_in_nav pattern.