Skip to content

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

  • 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)

Locked decisions

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

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)

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/platform/.pages, docs/platform/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.

  • Cloudflare Pages: https://developers.cloudflare.com/pages/
  • MkDocs Material: https://squidfunk.github.io/mkdocs-material/
  • Cloudflare Access for self-hosted apps: https://developers.cloudflare.com/cloudflare-one/applications/configure-apps/self-hosted-public-app/