Skip to content

05 — Appendix

Alternatives evaluated

Astro Starlight

Pros: modern, framework-flexible, good defaults, custom-friendly. Cons: more configuration surface, JavaScript build pipeline, requires familiarity with Astro components for customization. Wins if we ever want interactive components in pages — which today, we don't. Verdict: valid runner-up. Reconsider if we outgrow MkDocs Material.

Docusaurus

Pros: popular, good docs ecosystem, versioning support out of the box. Cons: React-heavy, slower builds, more bundled JS for readers, opinionated structure that doesn't match our projects/ + platform/ shape. Verdict: mismatch. Optimized for product API docs with versioned releases — not engineering plans.

GitHub Pages on a private repo

Pros: simplest possible setup. Cons: Pages on private repos requires GitHub Enterprise. Auth is GitHub team membership, not Cloudflare Access — breaks the consistency with the rest of Adventive's auth model. Less flexible Access-policy granularity. Verdict: rejected on auth-model fragmentation.

Notion / Confluence

Pros: in-browser editing, comments, share-by-link. Cons: breaks "source of truth is the file" model. WeasyPrint PDFs lose fidelity when pasted in. No git history. Markdown structure flattens. Locks content into a vendor. Verdict: rejected. Better suited to free-form ops content than structured engineering docs.

Self-hosted wiki (BookStack, Outline, etc.)

Pros: full feature set, user accounts, comments. Cons: server to maintain, backups to manage, auth to integrate, marginal cost. Solving a problem we don't have. Verdict: rejected. Static site + git is dramatically less ops burden.

Risks

Risk Likelihood Impact Mitigation
MkDocs Material plugin churn breaks build Low Low Pin versions in requirements.txt; bump intentionally
Cloudflare Access misconfiguration locks Jeffrey out Low Medium Always include a fallback "service-token" policy; test policy changes against a staging URL first
Sensitive content leaks via search index Low High Search runs entirely client-side; index contains only what's already on the gated site. Reviewing what gets committed is the real control.
PDF size bloat slows clones Medium Low If the repo grows past ~500 MB, move PDFs to Git LFS

Decisions resolved 2026-04-27

All four kickoff questions were answered and recorded as ADRs in decisions/:

# Question Resolution ADR
1 Repo strategy This folder IS the docs repo; content under docs/ (amended post-strict-build) 2026-04-27-repo-this-folder-becomes-source.md
2 Production hostname docs.adventive.dev 2026-04-27-subdomain-docs-adventive-dev.md
3 Identity provider JumpCloud 2026-04-27-idp-jumpcloud.md
4 Content exclusions _archive/, _proposed/, all code/, all inputs/, handoff/, connector-rewrite/, worker-stub/ 2026-04-27-content-exclusions.md

Verification status

  • mkdocs build --strict runs clean against the workspace as of 2026-04-27 (re-verified after link cleanup). Build output: 64 HTML pages generated in ~2.8 seconds with zero warnings at INFO or higher.
  • Relative links into excluded directories (worker-stub/, connector-rewrite/) were rewritten to GitHub repo URLs so site readers can still browse those source trees on GitHub even though the directories are intentionally excluded from the rendered site.
  • pygments<2.20 pin in requirements.txt is required — Pygments 2.20 introduced a regression in pymdownx.highlight that crashes on un-tagged code fences. Remove the cap when pymdown-extensions ships a fix.
  • The three previously-empty decisions/ folders (cloudflare-tunnel-rollout, google-data-studio-connector, public-api-cf-migration) now contain stub READMEs so awesome-pages doesn't fail when a .pages nav references them.
  • scripts/init-repo.sh is staged at the workspace root: a single command that runs git init, the initial commit, and gh repo create … --push against adventive/adventive-engineering-docs. Idempotent preflight checks bail out if .git already exists.

Remaining work for Jeffrey

  1. From the workspace root, run ./scripts/init-repo.sh to git init, commit, and gh repo create against adventive/adventive-engineering-docs (private GitHub repo). The script does preflight checks and prints next steps.
  2. In Cloudflare Pages: connect the repo, set build command + output directory per 02-code-updates.md, deploy.
  3. Add docs.adventive.dev as a custom hostname on the Pages project.
  4. In Cloudflare Zero Trust: configure JumpCloud SAML, create the engineering-docs-readers group binding, attach the Access policy to docs.adventive.dev.
  5. Verify allow + deny paths with two test accounts.
  6. Send the URL to engineering colleagues.

References