Skip to main content

Context​

Once the organization was created (see ADR-0001), the immediate need arose to document products, glossary, runbooks, decisions, and internal processes. Without a defined home, that information scatters across READMEs, chat threads, loose documents, and individual memory. We need a single search and reference mechanism that serves both people and AI agents collaborating on the project.

On top of that, there is a privacy requirement: the content covers products under development, internal decisions, and sensitive infrastructure, so hosting must sit behind real authentication, not just "unlisted".

Decision​

We create the repo eigenoid/internal-docs as the single home for the project's internal documentation (products, glossary, runbooks, ADRs, ops), built with Docusaurus and deployed on Cloudflare Pages behind Cloudflare Access (Zero Trust Free, GitHub as IdP).

Consequences​

  • Single source of truth: any person or agent knows where to find and where to write documentation.
  • Docs-as-code: content lives in Markdown alongside its git history; changes are reviewed via PR just like code.
  • Docusaurus tooling: auto-generated sidebar, local search, versioning, and theming without building it from scratch.
  • Real private hosting: Cloudflare Access ensures only GitHub-authenticated members can see the site, which GitHub Pages on Free/Team plans does not offer (always serves publicly).
  • Node toolchain cost: contributing requires node + npm, which adds friction for non-technical writers.
  • Docusaurus lock-in: migrating to another tool in the future involves work (frontmatter, MDX, custom plugins). We accept this lock-in consciously.

Alternatives considered​

  • Notion / Confluence / Google Docs: friendlier editor, but breaks docs-as-code (no PRs, no granular history, no search integrated with the code). Also paid SaaS for serious use.
  • Distributed READMEs in each repo: zero infrastructure, but documentation ends up fragmented and duplicated; no global index or search.
  • Other SSGs (MkDocs, Astro Starlight, Nextra): comparable in features, but the team already knows React/Docusaurus and its plugin ecosystem is more mature.
  • GitHub Pages: free and native, but always serves publicly on Free/Team plans; a direct blocker for confidential internal docs.

References​