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
    guides/
      getting-started.html
    theme/
      custom.css

Files and Directories

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. Use --clean to remove it before rebuilding.

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:

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
• Theming — CSS variables, custom CSS, and template overrides
• Installation — creating your first project