Backend Services - MkDocs¶

This service builds the Developer Documentation and API Reference sites from multiple GitHub repositories. It is designed to run inside a container and automatically rebuild when triggered via webhook.

The result is two static sites:

Site	Description
Developer Documentation	Bundles docs from multiple repos + README + Changelog
API Reference	Standalone Swagger-UI site for OpenAPI specs

How it Works¶

The build process clones one or more GitHub repositories listed in GH_REPOS.
For each repo, it:
Copies the repo’s docs/ folder into the generated site
Ensures docs/index.md exists (stubs if missing)
Copies the repo root README.md → <repo>/readme.md
Copies the repo root CHANGELOG.md → <repo>/CHANGELOG.md
Stubs missing README or CHANGELOG files
A landing page (index.md) is generated listing all repos:

<repo name>
  Readme
  Docs
  Changelog

A section break is inserted, then a final link:

---
API Reference

MkDocs builds the Developer docs site
Swagger-UI builds the API docs site

Everything is written to:

/out/developer   → mkdocs site
/out/api         → swagger-ui site

README Ingestion¶

Each repo’s root README.md is automatically copied into its docs section.

Important: To avoid MkDocs treating README.md as an implicit index.md, it is renamed to readme.md inside the generated docs tree.

Example structure inside the doc site:

out/developer/
  org-repo/
    index.md         ← From docs/
    readme.md        ← From repo/README.md
    CHANGELOG.md     ← From repo/CHANGELOG.md

It then appears in the site navigation under each repo:

<repo>
  Readme
  Docs
  Changelog

If README.md is not found, a stub is created so navigation always renders.

Changelog Support¶

Each repo must contain a CHANGELOG.md. If missing, a stub file is generated so the navigation remains stable.

Displayed under each repo as:

Changelog

Each repo produces a navigation block in this order:

<repo>
  Readme
  Docs
  Changelog

A horizontal rule separates repo sections from API docs:

---
API Reference

Environment Variables¶

Env Var	Required	Description
`GH_REPOS`	✅	Comma list of org/repo or org/repo@branch
`GH_PAT`	✅	GitHub Personal Access Token (read-only OK)
`OPENAPI_REPO`	✅	Repo containing OpenAPI spec
`OPENAPI_PATH`	✅	Path inside repo to spec (json/yaml)
`SITE_NAME`	✅	Title used by MkDocs
`SITE_URL`	✅	Public site URL
`API_URL`	✅	Public API docs URL
`OUT_DEV`	✅	Folder for mkdocs output
`OUT_API`	✅	Folder for swagger-ui output

Example GH_REPOS:

GH_REPOS="org/AOS,org/Backend@main,org/Design"

Development¶

Run in dev mode:

docker compose -f docker-compose.base.yml -f docker-compose.dev.yml up --build mkdocs

Then trigger a manual build:

curl -X POST -H "Authorization: Bearer $DOCS_BUILD_TOKEN" http://localhost:8001/build

Built files appear under your bind mounts:

out/developer/
out/api/

Implementation Notes¶

Why rename README.md → readme.md?¶

MkDocs treats README.md as an alias for index.md and will exclude it if index.md also exists. Since each repo has its own docs/index.md, the README.md from repo root would get ignored.

Renaming to readme.md guarantees: ✅ No conflict ✅ Always included ✅ Navigation links work

Stub Rules¶

If any file is missing, a stub is created:

File	Stub
README.md	`_No README found in repo root._`
CHANGELOG.md	`_No entries yet._`
docs/index.md	Created dynamically

Output Layout Example¶

/out
  /developer
    index.html
    org-Design/
      index.html
      readme.html
      CHANGELOG.html
    org-Backend/
      ...
  /api
    index.html
    openapi.json

Triggering via Webhook¶

This service is intended to be fed from GitHub push events. You can also trigger manually via:

POST /build
Authorization: Bearer $DOCS_BUILD_TOKEN

Payload is optional.

< Backend Services - Redis Exporter

Next: Backend Deployment - Overview >