Monorepo Docs Strategy¶

This project is now set up to run documentation with MkDocs as an independent service-friendly surface.

Local Serve Contract¶

Serve command and address:

uv run --group dev mkdocs serve --config-file mkdocs.yml --dev-addr 0.0.0.0:9000

This is the same command used by just docs-serve.

Monorepo-Friendly Structure¶

• Keep app docs under apps/api/docs/
• Keep MkDocs config in apps/api/mkdocs.yml
• Standardize each project to expose a docs-serve command on port 9000

If you later introduce a monorepo root docs gateway, each project can be mounted or proxied as its own docs service without changing page content.

Service Readiness¶

To make docs a standalone service in CI/CD or containers, use this lifecycle:

1. Install dependencies for docs tooling
2. Run mkdocs build for static output
3. Serve static output with a web server in production
4. Use mkdocs serve only for local development

Suggested Next Step for Multi-Project Aggregation¶

When you are ready to aggregate multiple project docs in one MkDocs site, introduce a dedicated root docs project and compose project sections there.

Keep this project's docs content self-contained so migration to an aggregator is copy-safe and predictable.