Skip to content
Ravens Pool Docs

Documentation and GitLab Pages

This site uses Starlight, built on Astro. Markdown stays in docs/; configuration, components, and the npm lockfile live in ci/docs/. The generated output is docs-site/.

Build and publication

flowchart LR
    Markdown[Markdown sources] --> Build[Starlight build]
    Locks[npm lockfile] --> Build
    Build --> Check[Local link and asset validation]
    Check --> Artifact[docs-site artifact]
    Artifact --> Branch{Default branch and all checks passed?}
    Branch -->|Yes| Pages[GitLab Pages]
    Branch -->|No| Preview[Downloadable artifact]

docs:build installs locked npm dependencies, builds the site and search index, and checks generated local links, heading anchors, and assets. External sites are not fetched by the link checker. The artifact is retained for seven days.

docs:pages runs on the default branch after the final-stage validation barrier, downloads that artifact, and publishes it with pages.publish: docs-site. The deployment does not expire and uses no Azure credentials. The Azure UI’s public/ directory is separate from the documentation build.

Finding the published site

After the first successful default-branch pipeline:

  1. Open the project’s Deploy → Pages screen.
  2. Follow the published URL shown there, or open the documentation environment.
  3. If needed, adjust Pages access control to the audience intended for these guides.

Use the actual URL shown by GitLab. Subgroups, unique Pages domains, and custom domains can change the address; no guessed hostname is embedded in the README. Starlight takes its canonical origin and base path from CI_PAGES_URL at build time so nested project paths work.

Publishing these guides does not publish the entire repository. The generated site contains documentation and theme assets, not player contact records, the roster PDF, Function state, or application credentials. Source-code links lead to GitLab and retain the repository’s own access controls.

Preview and authoring

Use Node.js 22.12 or newer and Python 3 for the generated-link check:

Terminal window
npm ci --prefix ci/docs
npm run dev --prefix ci/docs

Open http://127.0.0.1:4321. Search is available in the production preview:

Terminal window
npm run build --prefix ci/docs
python3 ci/docs/check_site.py docs-site
npm run preview --prefix ci/docs

Add Markdown files under docs/ with a title in YAML frontmatter and register them in the sidebar in ci/docs/astro.config.mjs. Starlight supplies the page heading, table of contents, search, edit links, and light/dark theme controls. Use relative .md links between guides; the Markdown plugin rewrites them to published URLs while keeping them usable in GitLab. Links to repository source outside docs/ should use a GitLab source URL.

To verify a nested Pages deployment, use the same URL for both commands:

Terminal window
CI_PAGES_URL=https://example.com/group/project npm run build --prefix ci/docs
CI_PAGES_URL=https://example.com/group/project python3 ci/docs/check_site.py docs-site

Mermaid diagrams

Write diagrams directly in Markdown:

```mermaid
flowchart LR
    Change[Commit] --> Checks[Validation]
    Checks --> Deployment[Deployment]
```

The Markdown plugin creates a keyboard-focusable scrolling region. The footer component loads the bundled Mermaid runtime only on pages with diagrams and renders them for the selected color theme. There are no CDN runtime requests. Keep explanatory prose alongside diagrams. Check diagrams in a browser after editing: the static build and link checker do not validate Mermaid syntax. The site uses system fonts and does not configure analytics.

Generator updates

Update exact package versions in ci/docs/package.json, run npm install --prefix ci/docs, and review ci/docs/package-lock.json. Build and check both root and subpath URLs, then review the browser preview, including search, diagrams, mobile navigation, and both color themes. Documentation dependencies are isolated from Python runtime and test packages and do not appear in the application’s Python SBOMs.