02 — Code & Configuration

One-time setup

Repository

cd ~/Documents/Claude/Projects/Adventive\ Engineering/
git init
git add -A
git commit -m "Initial commit — restructured 2026-04-27"
gh repo create adventive/adventive-engineering-docs --private --source=. --push

`mkdocs.yml` — minimal first pass

site_name: Adventive Engineering
site_description: Plans, runbooks, and platform standards for Adventive Platform Engineering.
site_url: https://docs.adventive.dev/
repo_url: https://github.com/adventive/adventive-engineering-docs
edit_uri: edit/main/

docs_dir: docs          # All authored content lives under docs/. mkdocs.yml stays at repo root.
exclude_docs: |
  _archive/
  _proposed/
  _shared/
  _templates/
  **/code/
  **/inputs/
  **/handoff/
  **/connector-rewrite/
  **/worker-stub/

theme:
  name: material
  custom_dir: overrides
  palette:
    - scheme: default
      primary: blue
      accent: blue
  features:
    - navigation.instant
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - content.code.copy
    - content.action.edit

plugins:
  - search
  - awesome-pages
  - git-revision-date-localized:
      type: timeago

markdown_extensions:
  - admonition
  - attr_list
  - tables
  - toc:
      permalink: true
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

`overrides/` — light theming

overrides/ lives at the repo root and is the Material custom_dir target. It contains template overrides only.
overrides/partials/copyright.html overrides the Material footer to read Adventive Platform Engineering · Confidential.
The Adventive accent CSS lives at docs/assets/extra.css (must be inside docs_dir) and is referenced from mkdocs.yml as extra_css: [assets/extra.css]. It applies the house-style accent color (#2563eb) and the navy/slate palette matching the WeasyPrint PDFs.

Per-folder `.pages` files (awesome-pages plugin)

Lets us control nav order without renaming. Example for projects/:

nav:
  - admin-dashboard-cf-migration
  - stripe-billing-transition
  - public-api-cf-migration
  - google-data-studio-connector
  - cloudflare-tunnel-rollout

Cloudflare Pages settings

Setting	Value
Build command	`pip install -r requirements.txt && mkdocs build`
Build output directory	`site`
Root directory	`/`
Environment variable	`PYTHON_VERSION=3.12`
Production branch	`main`
Preview deployments	Enabled — every PR gets a preview URL

requirements.txt (at repo root):

mkdocs-material==9.5.*
mkdocs-awesome-pages-plugin==2.9.*
mkdocs-git-revision-date-localized-plugin==1.2.*
mkdocs==1.6.*
pymdown-extensions==10.7.*
pygments<2.20            # 2.20 broke pymdownx.highlight; remove cap when upstream fixed

Cloudflare Access policy

Field	Value
Application type	Self-hosted
Application domain	`docs.adventive.dev`
Identity providers	JumpCloud (SAML)
Policy	”Allow if `Email ends with @adventive.com` AND `Group is engineering-docs-readers`”
Session duration	24 hours
App launcher visibility	On

Preview deployments land on *.adventive-engineering-docs.pages.dev. Add a second Access app covering that pattern with the same JumpCloud policy so previews are gated identically to production.

What gets committed vs. ignored

.gitignore:

.DS_Store
site/                   # mkdocs build output
.venv/
__pycache__/
*.pyc

Everything else — Markdown, PDFs, inputs/, code/ mirrors, decisions/ — gets committed. PDFs are large but rare; LFS is only needed if any single PDF exceeds ~50 MB (none currently do).

Ongoing change flow

Author or edit Markdown in the appropriate docs/projects/<name>/ or docs/platform/cloudflare/<service>/ folder.
Build the WeasyPrint PDF (existing per-project build_pdf.py if present; otherwise authored separately).
Commit and push to a branch; open PR.
Pages builds a preview deployment; reviewer reads it on the preview URL.
Merge → main → site rebuilds within 1–2 minutes.