Skip to content

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.