Skip to content

docs-deploy

Audience: Agent

Purpose

Build and serve the EDOS documentation site from this workspace’s docs/ tree: MkDocs Material for themed HTML at /, plus nginx so agents can fetch /raw/*.md (Markdown aligned with repo docs/ except templates/, which is stripped at image build time). Production host: docs.edos.howfe.org.

Tech stack

  • MkDocs Material — site config in docs-deploy/mkdocs.yml
  • nginx — static HTML + /raw/ Markdown (docs-deploy/nginx/)
  • Docker — multi-stage docs-deploy/Dockerfile; Compose in docs-deploy/docker-compose.yaml

Layout

Path Role
docs-deploy/mkdocs.yml Nav, theme, Mermaid via pymdownx.superfences
docs-deploy/docker-compose.yaml Traefik host rule, registry image registry.gitlab.com/elite-dangerous1/edos:docs
docs-deploy/Dockerfile Build docs/ → nginx image (see DEPLOYMENT.md for /raw/ behavior)
docs-deploy/README.md Local mkdocs serve from workspace root

Integration points

  • CI: repository root .gitlab-ci.yml builds and pushes the :docs image; operator deploy copies Compose to the server (see docs-deploy/README.md).
  • Content: all authored pages live under workspace docs/; this folder only packages them.

Extension points

  • Add pages under docs/ and wire them in docs-deploy/mkdocs.yml nav.
  • If the registry project path changes, edit the image: line in docs-deploy/docker-compose.yaml (see DEPLOYMENT.md).

Pitfalls / checks

  • templates/ is for local bootstrap snippets — not published on the docs site; do not assume hosted /raw/ includes those files.
  • Local preview needs Python + mkdocs-material installed (pip install mkdocs-material).