Skip to content

0004 — Knowledge base with MkDocs Material

  • Status: Accepted
  • Date: 2026-07-22

Context

The project needs a "local LLM wiki" — a place to store knowledge, decisions and planning that is (a) easy to edit locally as plain text, (b) friendly to git and AI tooling, and (c) presentable to employers.

Options considered: an Obsidian vault (great for personal linking, but not a published site out of the box), a plain docs/ folder of Markdown (simplest, but unstyled), and MkDocs + the Material theme (Markdown that renders to a polished, searchable website).

Decision

Author the knowledge base as Markdown in docs/, rendered by MkDocs Material and published to GitHub Pages via GitHub Actions.

Consequences

  • ✅ Source stays plain Markdown — trivial to edit locally and diff in git.
  • ✅ Produces a polished, searchable, mobile-friendly site — a strong portfolio signal (live, published documentation).
  • ✅ CI rebuilds and deploys on every push to main; no manual publishing.
  • ⚠️ Adds a small toolchain (Python package + a GitHub Actions workflow), which we document so setup stays reproducible.