Project Structure

A DocAnvil project has a simple directory layout. Here's the complete structure:

my-project/
  docanvil.toml           # Project configuration
  nav.toml                # Navigation structure (optional)
  docs/                   # Content directory (configurable)
    index.md              # Home page
    guides/
      getting-started.md
      configuration.md
    reference/
      cli.md
  theme/                  # Theme customization
    custom.css            # Custom stylesheet
    templates/            # Template overrides (optional)
      layout.html
  dist/                   # Build output (generated)
    index.html
    search-index.json     # Full-text search index (when search enabled)
    guides/
      getting-started.html
    theme/
      custom.css

Files and Directories

Here's what each part of the project does.

docanvil.toml

The main configuration file. Contains project name, content directory path, build output path, and theme settings. See Configuration for the full reference.

nav.toml

Controls the sidebar navigation structure. Defines page order, separators, groups, and label overrides. If this file is absent, DocAnvil auto-discovers pages from the content directory and builds navigation alphabetically.

Content Directory

The docs/ directory (configurable via content_dir in docanvil.toml) contains all your Markdown source files. Any .md file placed here becomes a page in the documentation.

Subdirectories create URL path segments. The directory structure maps directly to the output structure.

Theme Directory

The theme/ directory holds customization files:

• custom.css — your CSS overrides, loaded after the default theme
• templates/layout.html — optional full template override using Tera

Output Directory

The dist/ directory (configurable via output_dir) is generated by docanvil build. It contains the complete static site ready for deployment, including a search-index.json file when search is enabled. Use --clean to remove it before rebuilding.

i18n Project Layout

When localisation is enabled, content files use locale suffixes and the build output is split into per-locale directories:

my-project/
  docanvil.toml           # Includes [locale] section
  nav.toml                # Default navigation (fallback)
  nav.fr.toml             # French-specific navigation (optional)
  docs/
    index.en.md           # English home page
    index.fr.md           # French home page
    guides/
      getting-started.en.md
      getting-started.fr.md
  dist/                   # Build output
    js/docanvil.js         # Shared across locales
    robots.txt
    sitemap.xml            # Contains all locales
    404.html
    en/
      index.html
      guides/
        getting-started.html
      search-index.json    # English search index
    fr/
      index.html
      guides/
        getting-started.html
      search-index.json    # French search index

See Localisation for a complete guide to setting up multi-language docs.

Versioned Project Layout

When versioning is enabled, content lives in version-named subdirectories and the build output is split per version:

my-project/
  docanvil.toml           # Includes [version] section
  nav.toml                # Default navigation (fallback for all versions)
  nav.v1.toml             # v1-specific navigation (optional)
  nav.v2.toml             # v2-specific navigation (optional)
  docs/
    v1/
      index.md
      getting-started.md
    v2/
      index.md
      getting-started.md
      new-feature.md
  dist/                   # Build output
    index.html            # Meta-refresh redirect to /v2/index.html
    js/docanvil.js        # Shared assets (one copy)
    robots.txt
    sitemap.xml           # All versions included
    404.html
    v1/
      index.html
      getting-started.html
      search-index.json   # v1 search index
    v2/
      index.html
      getting-started.html
      new-feature.html
      search-index.json   # v2 search index

When versioning and i18n are both enabled, locale directories nest inside version directories:

dist/
  v2/
    en/
      index.html
      search-index.json
    fr/
      index.html
      search-index.json

See Versioning for a complete guide to setting up multi-version docs, including navigation, the version switcher, and composing with i18n.

Page Discovery

DocAnvil discovers pages by walking the content directory recursively and collecting all .md files. Each file becomes a page with a slug, title, and output path.

Slug Derivation

The slug is the file path relative to the content directory, with the .md extension removed and backslashes normalized to forward slashes:

Front Matter Slug Overrides

When a page has a title in its front matter, the slug is derived from the title instead of the filename. An explicit slug front matter field takes priority over both. This lets you use organizational prefixes in filenames while keeping clean URLs:

Directory prefixes are preserved — only the filename portion changes. Pages named index.md are exempt from title-derived slugs. See Front Matter for full details.

Wiki-links using the old filename-based slug continue to resolve after a slug override.

Locale-Aware Slugs

When i18n is enabled, the locale suffix is stripped before building the slug. The locale is tracked separately and the output path includes a locale prefix:

Files without a locale suffix are assigned the default locale. See Localisation for details.

Title Generation

Titles are derived from the slug's last path component:

• index becomes "Home"
• Hyphens and underscores become spaces
• Each word is capitalized (getting-started → "Getting Started")

Titles appear in the sidebar navigation (unless overridden by label in nav.toml) and in the page's <title> tag.

Auto-Discovery Navigation

When nav.toml is absent, the navigation tree is built from the directory structure:

• Top-level .md files become root nav items
• Subdirectories become collapsible groups, labeled with the directory name in title case
• Files within directories become children of their group
• Everything is sorted alphabetically

Related Pages

• Configuration — docanvil.toml and nav.toml options
• Versioning — multi-version directory layout and build output
• Theming — CSS variables, custom CSS, and template overrides
• Installation — creating your first project