# MkDocs Configuration Model

Each documentation kind (lib, api, wiki) is built by its own MkDocs site. A
repo that documents kind `{kind}` carries a config at `docs/mkdocs.{kind}.yml`
that sets `docs_dir` to the kind's source directory and `site_dir` to
`../site/{kind}`.

---

## 📄 File wins

`docs/mkdocs.{kind}.yml` is a repo-owned file, not a build byproduct:

- **Absent** — `doc-forge build --{kind}` materializes a copy from the
  packaged templates (see below) and then builds `site/{kind}`.
- **Present** — the build uses the file verbatim. Edits to the theme, palette,
  plugins, markdown extensions, nav, or `site_dir` are respected as-is.
- **`--refresh`** — force-regenerates the file from the templates,
  replacing any local changes.

Because a present file is never rewritten, rerunning a build is a no-op for
versioned configs: the working tree stays clean.

---

## 🧩 Templates

The built-in defaults live in `docforge/templates/`:

| File                  | Role                                          |
|-----------------------|-----------------------------------------------|
| `mkdocs.common.yml`   | Shared theme + markdown extensions            |
| `mkdocs.lib.yml`      | `mkdocstrings` handler for library reference  |
| `mkdocs.api.yml`      | Swagger/OpenAPI plugins and API-side features |
| `mkdocs.wiki.yml`     | Wiki look: horizontal `navigation.tabs` header, blue grey/teal palette, Roboto |

A per-kind config is generated by deep-merging the common template with the
kind fragment, then filling in generation-time values (`site_name`,
`docs_dir`, `site_dir`, `nav`, API `site_description`/`site_author`, and the
theme `icon` from `docforge.nav.yml`). Pass `--template <path>` to replace the
built-in templates entirely.

---

## 🏗️ Supported layouts

- **Per-kind config** — the standard layout; each kind builds to
  `site/{kind}` and is served under `/<repo>/{kind}/`.
- **Legacy root config** — a repo with a single kind may instead author root
  `mkdocs.yml` (for example mongo-ops, whose wiki uses `docs_dir: docs/wiki`).
  doc-forge never reads or writes root `mkdocs.yml`; the docs service maps the
  kind to the root `site/` dir in this case.

Commit `docs/mkdocs.{kind}.yml` so served docs are reproducible from source.

---

## Related
- [04 – MCP Guide](04_mcp_guide.md)