Skip to content
Adventive Adventive Engineering

Engineering Docs Site

Publish this Adventive Engineering/ folder as a navigable, searchable static site for engineering colleagues, gated by Cloudflare Access at docs.adventive.dev.

Status

Section titled “Status”
  • Owner: Jeffrey Lambert
  • Status: Decisions locked, implementation staged 2026-04-27, mkdocs build --strict verified clean (zero warnings) 2026-04-27: pending Jeffrey running ./scripts/init-repo.sh and Cloudflare Pages + Access provisioning
  • Started: 2026-04-27
  • Production URL: https://docs.adventive.dev (pending DNS + Pages setup)
  • Repository (planned): adventive/adventive-engineering-docs (this folder, once git init + remote add)

Publishing: validated ≠ deployed

Section titled “Publishing: validated ≠ deployed”

Two separate pipelines act on a push to main, and it is easy to mistake one for the other:

  • .github/workflows/build.yml (“Validate docs build”) runs npm run check and npm run build (Astro + starlight-links-validator) and uploads the dist/ artifact. It validates; it does not publish. A green run here means the site builds, not that it is live.
  • Cloudflare Pages is what publishes docs.adventive.dev. It builds from main on every commit and deploys the result. If a change validated but isn’t visible, check the Pages deployment (did it build the latest commit?) and purge the edge cache / hard-refresh — not the GitHub Actions run.

New pages also need a sidebar entry: most sections use autogenerate, so a new file appears automatically, but ENGINEERING RESOURCES and a few top-level links are listed explicitly in astro.config.mjs and must be added there by hand.

Locked decisions

Section titled “Locked decisions”
#DecisionADR
1The Adventive Engineering/ folder IS the docs repo (no mirroring)decisions/2026-04-27-repo-this-folder-becomes-source.md
2Production hostname: docs.adventive.devdecisions/2026-04-27-subdomain-docs-adventive-dev.md
3Auth via Cloudflare Access, identity bound to JumpClouddecisions/2026-04-27-idp-jumpcloud.md
4Exclude _archive/, _proposed/, all code/, all inputs/decisions/2026-04-27-content-exclusions.md

What’s in this folder

Section titled “What’s in this folder”
  • 00-context.md: why we’re doing this, what it replaces
  • 01-architecture-assessment.md: MkDocs Material on Cloudflare Pages behind Access
  • 02-code-updates.md: repo layout, build config, Pages settings, Access policy
  • 03-deployment-management.md: CI/CD via GitHub Actions, observability
  • 04-runbook.md: how to add a project, publish a draft, restrict a doc
  • 05-appendix.md: alternatives evaluated, references
  • decisions/: ADRs locked 2026-04-27

Implementation files (staged 2026-04-27)

Section titled “Implementation files (staged 2026-04-27)”

At repo root:

  • README.md: thin GitHub-browser README
  • mkdocs.yml: docs_dir: docs
  • requirements.txt: pinned MkDocs Material + plugins; pygments<2.20 cap
  • .gitignore
  • .github/workflows/build.yml: PR validation
  • overrides/partials/copyright.html: Material theme footer override

Inside docs/:

  • docs/README.md: site landing page
  • docs/assets/extra.css: Adventive theme CSS
  • docs/projects/.pages, docs/system-infrastructure/.pages, docs/system-infrastructure/cloudflare/.pages: explicit nav order
  • Per-project .pages files for chapter ordering inside each project

The original ADR specified docs_dir: . (no docs/ subdirectory). MkDocs 1.6 forbids this. The ADR was amended 2026-04-27 to allow a single docs/ subdirectory; intent (single source of truth, no copy/sync) is preserved. See decisions/2026-04-27-repo-this-folder-becomes-source.md.

Section titled “Quick links”