Skip to content

Wiki Architecture: Markdown + Git over SaaS

Decided on 2026-04-07 — Scope: Company

Context

GYC needed a system to document institutional knowledge — processes, people, projects, decisions — that would: 1. Survive 30+ years without vendor dependency 2. Be consumable by future AI agents 3. Integrate with the existing OPS Dashboard and Google Workspace ecosystem 4. Support voice-to-text capture of PM meeting brain dumps 5. Not require constant maintenance overhead

Decision

Build the GYC internal wiki as plain Markdown files in a Git repository, using: - Obsidian as the primary editor (desktop) - Git for version control and collaboration - YAML frontmatter for structured metadata on every document - MkDocs Material as a future read-only web publishing layer - WhisperX + Ollama for voice-to-wiki transcription pipeline

Alternatives Considered

  1. Notion — Rejected due to vendor lock-in, proprietary format, and cumulative subscription costs over 30 years. Data export quality is unreliable.

  2. Confluence — Rejected for the same reasons as Notion, plus excessive complexity for a small team. Atlassian ecosystem is overkill.

  3. Outline (self-hosted) — Considered seriously. WYSIWYG editing is attractive for non-technical users. Rejected because it still requires database infrastructure and adds operational overhead. Could revisit as a presentation layer on top of the Markdown repo.

  4. BookStack (self-hosted) — Similar to Outline. Good WYSIWYG editor but adds infrastructure complexity.

  5. Google Sites / Google Docs wiki — Would keep everything in the existing Google ecosystem. Rejected because Google formats are not AI-native, version history is limited, and there's no structured metadata support.

Rationale

The critical insight: the format is more important than the tool. Over 30 years, tools will change many times. But plain text Markdown files: - Are readable by any computer, any operating system, forever - Are the native input format for every LLM and AI system - Have zero vendor dependency - Are version-controlled through Git (full audit trail) - Can be served through any number of presentation layers (Obsidian today, MkDocs, Docusaurus, or whatever exists in 2040)

Inspiration: Karpathy's llm-wiki pattern — "compile knowledge once and keep it current, not re-derive on every query."

Impact

  • All institutional knowledge documentation will use Markdown + Git
  • The OPS Dashboard will eventually integrate wiki search
  • Future AI agents will have direct access to the entire knowledge base
  • Team members need basic familiarity with Obsidian or a text editor (no Git knowledge required for readers)

Follow-Up

  • Evaluate adding a CLAUDE.md / AGENTS.md schema file for LLM agent instructions
  • Set up GitHub remote for the wiki repo
  • Evaluate MkDocs Material for team-wide read-only web access
  • Build the voice-to-wiki pipeline