DECISIONS

MkDocs is the rendering engine

docs-kit uses MkDocs to render documentation sites. Rendering Markdown, building navigation, serving locally, and producing static HTML are mature responsibilities that MkDocs already handles well.

Material is the default theme

Material for MkDocs is the default theme because it provides a polished documentation experience with search, responsive layout, syntax highlighting, and dark/light mode support with little customization.

docs-kit orchestrates rather than replaces MkDocs

docs-kit should remain a focused CLI that prepares inputs, writes a generated MkDocs configuration, and invokes MkDocs. It should not become a custom Markdown renderer or theme framework.

Configuration should remain intentionally small

The public configuration API should stay compact and predictable. A small object with site identity, base path, and Markdown sources should cover the common case.

Documentation is generated from canonical Markdown

Projects should keep documentation in their canonical Markdown files. docs-kit copies those files into a generated workspace rather than requiring duplicated content.

Filesystem publishing uses complete releases

docs-kit publishes complete static releases under a configured deployment root and atomically advances a current symlink after the copied release validates. This keeps a partially copied site from becoming active and makes rollback a symlink update to an existing release.

Release directories are immutable once activated. Age-based retention may remove old inactive releases, but it must preserve the active release and the most recent rollback candidate.

Publishing one project updates one subtree in a complete snapshot

One docs-kit installation may host multiple independently built projects under one deployment root. A new release therefore clones the active release, removes the subtree selected by the publishing project's basePath, copies the new generated site into that subtree, validates it, and then atomically activates the new release.

This preserves unrelated paths such as /docs-kit/ when publishing /screeps/. It also keeps rollback simple and reliable: rollback always restores the complete hosted tree as it existed in the selected release.

The publisher uses a deployment lock under the publish root while it reads the active release, creates the next snapshot, replaces the project subtree, and activates current. Without that serialization, concurrent publishes from different repositories could clone the same active release and the later activation could discard the earlier one.

Publishing to basePath: "/" is only allowed for the first release. Once a release is active, root-path publication would mean replacing the entire hosted tree, so docs-kit rejects it until root composition has an intentional design.

The web server only reads the active release

docs-kit does not configure nginx, reload nginx, manage DNS, manage TLS, invoke Certbot, use sudo, or change ownership. Server-specific setup belongs to the operator. docs-kit only prepares release contents and the current symlink that a web server can read.

The project owns its URL path through basePath. During filesystem publishing, a project with basePath: "/docs-kit/" is copied into <release>/docs-kit/ so a server rooted at current can serve the documentation at /docs-kit.

Shared documentation-root pages are generated from manifests

Filesystem publishing maintains a machine-readable site registry under <publish-root>/shared/sites/. Each published site owns one manifest keyed by its normalized basePath. The registry lives outside immutable release directories so pruning old releases cannot silently unregister a site.

During a non-root publish, docs-kit writes the current site's manifest, reads all valid manifests, and renders shared index.html and 404.html into the new complete release before activating current. Malformed or unsupported manifests are skipped and reported rather than blocking unrelated sites. Rendering happens while the deployment lock is held, which serializes concurrent publishes for the same deployment root.

The shared root pages are plain static HTML, not another MkDocs site. They avoid runtime dependencies, escape generated content, and use only manifest data that is safe to show publicly. If shared-root rendering fails, docs-kit removes the incomplete release and leaves the previously active release unchanged.

Publishing a site at basePath: "/" remains a compatibility path for a first release, but docs-kit skips shared root page generation in that case because the root site owns /index.html.