# 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

### `docanvil.toml`

The main configuration file. Contains project name, content directory path, build output path, and theme settings. See [[guides/configuration|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.

## 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:

| Source File | Slug | Output File | Title |
|-------------|------|-------------|-------|
| `docs/index.md` | `index` | `index.html` | Home |
| `docs/guides/getting-started.md` | `guides/getting-started` | `guides/getting-started.html` | Getting Started |
| `docs/reference/cli.md` | `reference/cli` | `reference/cli.html` | Cli |
| `docs/writing/wiki-links.md` | `writing/wiki-links` | `writing/wiki-links.html` | Wiki Links |

### 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

:::note
Files are sorted by path during discovery, ensuring deterministic navigation order regardless of filesystem ordering.
:::

## Related Pages

- [[guides/configuration|Configuration]] — `docanvil.toml` and `nav.toml` options
- [[guides/theming|Theming]] — CSS variables, custom CSS, and template overrides
- [[guides/getting-started|Installation]] — creating your first project
