Skip to content

Documentation

This docs site lives in documentation/ of the Ampora repo. It is built with MkDocs Material and published to GitLab Pages from master and from every Git tag matching v*.

Local preview

cd documentation
python -m venv .venv
source .venv/bin/activate     # on Windows: .venv\Scripts\activate
pip install -r requirements.txt
mkdocs serve --strict

--strict fails the build on broken links, unknown nav entries, or missing files. Run it locally so CI does not surface surprises.

Adding a page

  1. Drop a Markdown file into the right documentation/docs/ subdir.
  2. Add it to the nav tree in mkdocs.yml. The build is --strict, so pages not wired into the nav fail CI on purpose — there is no "orphan" page.
  3. Cross-link with relative Markdown paths ([See concepts](../overview/concepts.md)), never bare URLs to the rendered site.

Style

  • Plain English, present tense, no marketing fluff.
  • Each page starts with a one-paragraph summary so search results read well.
  • Code blocks have explicit language tags (```yaml, ```bash, ```csharp) so highlighting works.
  • Wrap CLI examples to ≤ 100 columns so the right side does not scroll.
  • Screenshots go under documentation/docs/assets/screenshots/ with a descriptive name and alt text.
  • Prefer tables for reference-y content, prose for narrative.

Per-page front-matter

Each page should have:

---
title: Page title
description: One sentence. Used for OpenGraph and search snippets.
---

Long descriptions become the meta description; keep them under 160 characters.

Cross-references

Use the style:

Avoid bare URLs to the rendered docs site — they cannot be link-checked at build time.

Diagrams

Mermaid is enabled. Use it for state machines, sequence diagrams, and component diagrams:

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Published
    Published --> Archived
```

For more elaborate diagrams (pixel-precise architecture renderings), draw them in your tool of choice and check in the SVG under assets/diagrams/.

What lives where

  • Overview — the elevator pitches and the vocabulary.
  • Tutorials — end-to-end walkthroughs.
  • Operator Manual — installation and operations.
  • User Manual — day-to-day product UX.
  • Reference — flat lookup tables.
  • Contributor Guide — this section.
  • Release Notes — flat reverse-chronological list.

When in doubt, ask: who is the target reader? An operator running the server is not the same person as a customer using the UI.

Publishing

GitLab Pages serves the site from the public/ artefact produced by the pages job in .gitlab-ci.yml. The job runs on every commit to the default branch and on every v* semver tag — mkdocs build --strict --site-dir public and Pages does the rest. No gh-pages branch, no Project Access Token setup needed.

For a version dropdown (master / v1.4.2 / latest) enable mike per the note in documentation/README.md. It is opt-in because it requires a Project Access Token with write_repository scope, which the default CI_JOB_TOKEN does not have on GitLab.com.

Editing existing pages

Per-page edit-on-GitLab links sit at the top right of every page on the rendered site. Click, fix, commit, push — your MR is the contribution.