Skip to content

ADR-0002: Continuous Documentation Publishing and Public Evolution via Material for MkDocs on GitLab Pages

Status

Accepted

Context

Swayrm is an open civic technology and grassroots governance project. To maintain radical transparency and encourage public trust, participation, and scrutiny from inception, the incremental evolution of the project (vision, domain definitions, deliberations, and architectural decisions) must be continuously accessible to the public via a modern, attractive, and responsive web portal.

The project repository is hosted on GitLab, which offers integrated CI/CD and hosting via GitLab Pages.

During deliberation, we evaluated:

  1. Authoring Format (AsciiDoc vs. Markdown):
    • AsciiDoc (.adoc) offers powerful technical publishing capabilities (modular transclusion via include::[], native admonitions, Antora integration), but introduces formatting friction with AI collaborators (Gemini, Claude, GPT) and breaks standardized agent forwarders (GEMINI.md, CLAUDE.md, AGENTS.md).
    • Markdown (.md) is the native, lowest-friction format for both human contributors and AI agents, natively rendered by GitLab and standard tooling.
  2. Site Generation Engines:
    • Astro Starlight: Modern and flexible, but introduces a large Node.js toolchain (package.json, lockfiles, node_modules) into a repository currently focused on conceptual specification and domain modeling.
    • Material for MkDocs: Standard in technical specifications; single YAML configuration (mkdocs.yml); zero JavaScript runtime in the repository; native search, responsive UI, dark/light themes, and git-based page timestamps.

Decision

  1. Retain Markdown as Canonical Authoring Format: All conceptual, domain, architectural, and deliberation documents will remain authored in Markdown (*.md) directly under docs/.
  2. Adopt Material for MkDocs: We will use mkdocs with the material theme to generate the static documentation portal.
  3. Automated Continuous Publishing via GitLab Pages:
    • Configure .gitlab-ci.yml with a pages job triggered on the default branch ($CI_DEFAULT_BRANCH).
    • Utilize squidfunk/mkdocs-material as the CI runner image to ensure fast, deterministic pipeline runs without heavy dependency setups.
  4. Make Evolution Visible:
    • Enable mkdocs-git-revision-date-localized-plugin with GIT_DEPTH: 0 in CI to surface the last-modified date and living history on each page.
    • Expose deliberations (docs/deliberations/) and ADRs (docs/decisions/) prominently in site navigation as first-class evolution artifacts.
  5. Entry Point: Provide docs/index.md as the public landing page summarizing the vision, core pillars, and roadmap.

Consequences

Positive

  • Zero Repository Clutter: No heavy dependencies, lockfiles, or node runtime files in the repo root; publishing is managed via a single mkdocs.yml and .gitlab-ci.yml.
  • Instant Public Accessibility: Every commit pushed to the default branch automatically refreshes the public GitLab Pages site.
  • Preserved AI Efficiency: AI collaborators can continue to read and edit Markdown with zero impedance or syntax errors.
  • Rich Documentation Experience: Readers gain access to instant client-side search, mobile responsiveness, tabbed code/content blocks, admonition callouts, and dark/light themes.

Negative / Trade-offs

  • Advanced AsciiDoc features like native include::[] are unavailable in pure Markdown, though MkDocs extensions (pymdownx.snippets) can provide transclusion if required later.
  • GitLab CI runner minutes will be consumed on each commit to the default branch (typically ~15–30 seconds per run).