Configuration

DocAnvil uses two configuration files at the root of your project: docanvil.toml for project settings and nav.toml for navigation structure.

docanvil.toml

[project]
name = "My Docs"

[project]
name = "My Docs"
content_dir = "docs"
[build]
output_dir = "dist"
base_url = "/my-project/"
[theme]
custom_css = "theme/custom.css"
color_mode = "both"
[theme.variables]
color-primary = "#059669"
font-body = "Georgia, serif"
[search]
enabled = true
[charts]
enabled = true
mermaid_version = "11"
[locale]
default = "en"
enabled = ["en", "fr"]
auto_detect = true
[locale.display_names]
en = "English"
fr = "Français"
[locale.flags]
en = "🇺🇸"
[version]
current = "v2"
enabled = ["v1", "v2"]
[version.display_names]
v1 = "v1.0"
v2 = "v2.0 (latest)"
[pdf]
cover_page = true
author = "Your Name"
paper_size = "A4"
[doctor]
max_paragraph_words = 150
heading_adjacent_separator = true

[project] Section

[build] Section

[theme] Section

Variables are specified as key-value pairs where the key is the CSS variable name (without --) and the value is any valid CSS value:

[theme.variables]
color-primary = "#059669"
color-bg = "#fafafa"
font-body = "Inter, sans-serif"
content-max-width = "960px"

See CSS Variables for the complete list of available variables.

[search] Section

When enabled, DocAnvil generates a search-index.json file at build time and adds a search input to the header. Search is powered by MiniSearch.js, loaded from a CDN on first use. Set enabled = false to remove the search UI and skip index generation.

[charts] Section

When enabled, pages containing :::mermaid blocks will load Mermaid.js and render diagrams client-side. When disabled, :::mermaid content renders as preformatted text.

[locale] Section

When both default and enabled are set, DocAnvil switches to multi-language mode: each locale gets its own URL prefix (/en/, /fr/), its own navigation and search index, and a language switcher appears in the header.

[locale]
default = "en"
enabled = ["en", "fr", "de"]
auto_detect = true

[locale.display_names]
en = "English"
fr = "Français"
de = "Deutsch"

[locale.flags]
en = "🇺🇸"    # Use US flag instead of default GB

[version] Section

When enabled is non-empty, DocAnvil switches to multi-version mode: each version gets its own URL prefix (/v1/, /v2/), its own navigation and search index, and a version switcher appears in the header. Pages in older versions automatically show a banner linking to the latest version.

[version]
current = "v2"
enabled = ["v1", "v2"]

[version.display_names]
v1 = "v1.0"
v2 = "v2.0 (latest)"

[pdf] Section

[doctor] Section

The [doctor] section configures the docanvil doctor readability linter. The default settings are intentionally permissive — tighten the threshold for higher-quality writing standards.

[doctor]
max_paragraph_words = 100          # Flag paragraphs over 100 words
heading_adjacent_separator = false # Disable the separator-next-to-heading check

nav.toml

The navigation file controls the sidebar structure. It uses TOML's array-of-tables syntax and supports pages, separators, and groups.

Page Entries

The simplest entry links to a page by its slug (the file path relative to content_dir, without the .md extension):

[[nav]]
page = "index"

[[nav]]
page = "guides/getting-started"

Label Overrides

By default, the sidebar label is derived from the slug (getting-started becomes "Getting Started"). Override it with label:

[[nav]]
page = "guides/getting-started"
label = "Installation"

Separators

Add visual dividers between sections. A labeled separator shows text:

[[nav]]
separator = "Guides"

An unlabeled separator draws a horizontal line:

[[nav]]
separator = true

Groups

Groups create collapsible sections in the sidebar. Each group has a label and an array of children in group:

[[nav]]
label = "Reference"
group = [
  { page = "reference/cli", label = "CLI Commands" },
  { page = "reference/project-structure" },
  { page = "reference/css-variables", label = "CSS Variables" },
]

Linked Group Headers

Add a page field to make the group header itself a clickable link:

[[nav]]
label = "Writing Content"
page = "writing/markdown"
group = [
  { page = "writing/wiki-links", label = "Links & Popovers" },
  { page = "writing/components" },
]

Clicking "Writing Content" navigates to the Markdown page, while the arrow expands the group.

Child Separators

You can add separators inside groups to organize children:

[[nav]]
label = "Reference"
group = [
  { page = "reference/cli", label = "CLI Commands" },
  { separator = "Project" },
  { page = "reference/project-structure" },
  { page = "reference/css-variables", label = "CSS Variables" },
]

Autodiscover

You can use the autodiscover option to selectively autodiscover a folder and add it to the navigation:

[[nav]]
autodiscover = "api"

You can also use autodiscover with a collapsible group:

[[nav]]
label = "Reference"
autodiscover = "reference"

Auto-Discovery Fallback

If nav.toml is absent, DocAnvil auto-discovers all .md files in the content directory and builds the navigation from the directory structure. Files are sorted alphabetically, and directory names become group labels.

Related Pages

• Theming — CSS variables, custom CSS, and template overrides
• PDF Export — full PDF export guide
• Versioning — multi-version docs setup and version switcher
• Project Structure — how files map to pages and slugs