Skip to content

Docs Portal & Operations

This page documents how the documentation portal works: how to run it, what the toolchain expects, how it is validated in CI, and how to migrate it into a standalone dichit-docs repository.

What this portal is

The portal is MkDocs Material rendering the Markdown corpus under docs/. MkDocs turns Markdown into a searchable static site; Material provides the theme, navigation, dark mode, and code/Mermaid rendering.

The Markdown files themselves are deliberately renderer-neutral:

  • No front-matter, no Docusaurus/MkDocs-only syntax.
  • Plain GitHub-flavored Markdown, tables, and mermaid code fences.
  • Relative links only.

That neutrality is what makes the portal portable — see Migrating to dichit-docs.

Tooling layout

Path Purpose
mkdocs.yml Site config: theme, nav, extensions, plugins, Mermaid
docs/ The Markdown corpus (single source of truth)
docs/index.md Portal landing page (MkDocs-only)
docs/assets/stylesheets/extra.css Brand palette + landing styles
docs/assets/javascripts/extra.js Mermaid initialization
docs/assets/logo.svg Brand mark
docs/overrides/main.html Material template overrides (title, announce bar)
requirements.docs.txt Python dependencies (pinned ranges)
Makefile Docs workflow (make docs, make docs-build, …)
scripts/docs/check_links.py Relative-link validator (authoritative link gate)
scripts/docs/mkdocs_hooks.py Build hook filtering a known-benign strict-mode warning
.github/workflows/docs.yml CI: validate + build + publish to GitHub Pages

Prerequisites

  • Python 3.10+ and python3 -m venv
  • Nothing else — the Markdown toolchain is independent of the Node.js stack. It does not require pnpm install or a database.

Quick start

make docs-bootstrap   # one-time: create .venv-docs and install dependencies
make docs             # serve live at http://127.0.0.1:8000

The dev server watches docs/ and rebuilds on save. Links in the sidebar match the nav tree in mkdocs.yml; the corpus order is defined there, not by the filesystem.

Common commands

Command What it does
make docs Live-reload preview server
make docs-build Build into site/; strict — fails on broken links
make docs-check Validate relative links in docs/ (fast, no build)
make docs-lint docs-check + docs-build (what CI runs)
make docs-deploy Push built site to gh-pages (admin only)
make docs-clean Remove site/

DOCS_STRICT=false make docs-build relaxes strict mode (useful when a page is a work in progress). site/ and .venv-docs/ are gitignored.

Adding or moving a page

  1. Add/rename the Markdown file under docs/.
  2. Update the nav: tree in mkdocs.yml so the page appears in the sidebar.
  3. Link to it from its neighbours and the landing page (docs/index.md).
  4. Run make docs-lint to confirm links and build are clean.

Because the sidebar is authored in mkdocs.yml, every page must be listed in nav — MkDocs errors on files that are in docs/ but missing from nav when strict is on. Use an index.md (or the folder README.md) as the section landing page when a section needs an intro.

CI / CD

.github/workflows/docs.yml runs on:

  • every push to dev and main
  • every pull request touching docs/, mkdocs.yml, or the docs tooling

The workflow:

  1. Sets up Python, installs requirements.docs.txt.
  2. Runs make docs-check (link validation).
  3. Runs make docs-build (strict build — catches broken nav entries, render errors).
  4. On main only, publishes the built site/ to GitHub Pages via the actions/upload-pages-artifact + actions/deploy-pages pair.

Link validation split. The corpus contains GitHub-era links to repo-root files (../../src/…, ../../.github/…, ../../AGENTS.md) that MkDocs cannot resolve inside docs_dir, so MkDocs link warnings are scoped off and strict still guards nav, structure, and render output. The authoritative link gate is scripts/docs/check_links.py, which resolves every relative link against the real filesystem (including repo root) and ignores link-bearing code fences (templates). Run it with make docs-check.

Publishing uses Pages with a workflow, not the gh-pages branch, so content and deployment config stay in the same repo. The Makefile's docs-deploy target exists for admins who prefer the classic gh-pages branch flow.

Mermaid

Mermaid diagrams are rendered from plain ```mermaid fences. Rendering needs:

  1. pymdownx.superfences with a mermaid custom fence (in mkdocs.yml).
  2. Mermaid loaded from a CDN + extra.js initialization.

The CDN (unpkg) is the only external runtime dependency of the site. To vendor Mermaid instead, download mermaid.min.js into docs/assets/javascripts/ and point extra_javascript at the local copy.

Migrating to a standalone dichit-docs repository

The goal is to move the portal to its own repo without editing the Markdown files. The following are the only things that need to move:

mkdocs.yml                     # site config + nav
docs/                          # the whole Markdown corpus (unchanged)
docs/index.md                  # landing page (MkDocs-only; keep or replace)
docs/overrides/                # Material template overrides
docs/assets/                   # brand assets + extra.css/extra.js
requirements.docs.txt
Makefile
scripts/docs/check_links.py
.github/workflows/docs.yml

Steps:

  1. Copy the paths above into a new dichit-docs repository (or move docs/ into content/ and set docs_dir: in mkdocs.yml).
  2. Update three values in mkdocs.yml:
  3. site_url (or export DOCS_SITE_URL)
  4. repo_url / repo_name (or export DOCS_REPO_URL)
  5. edit_uri (point at the new repo's default branch)
  6. If the move renames docs/, update docs_dir and the nav paths.
  7. Enable GitHub Pages → Deploy from a branch or keep the workflow-based deploy and switch it to the new repo's Pages settings.

Do not touch the content Markdown: relative links, ```mermaid blocks, and tables all render identically in the standalone repo.