Skip to content

MkDocs Material PKB publishing stack

This is a blueprint

The concrete, copyable artefact a decision produced.

The stack for a git-backed, plain-Markdown personal knowledge base that publishes to a static site, produced by the Building my visual PKB decision. It is set out in three parts: the component manifest, the principles it instantiates, and the operating manual.

Manifest - what is assembled, and why each piece

  • MkDocs + Material for MkDocs
  • static site generator + theme; builds plain Markdown into a searchable site. Pin MkDocs <2 (Material is not yet 2.0-compatible).
  • Plugins - awesome-pages (nav without a hand-maintained tree), obsidian-support (Obsidian callouts → Material admonitions), excalidraw (client-side .excalidraw rendering, light/dark), backlinks-section, glightbox (image lightbox), git-revision-date-localized.
  • uv - the single toolchain: manages the Python version and all dependencies; no other global install required.
  • Git + Git LFS - LFS stores binary/opaque assets (.png, .svg, .excalidraw) out of line.
  • Pre-commit (via prek) - markdown lint, link checking, formatting and repo-hygiene guards.
  • GitHub Actions → GitHub Pages - on push to main, build with mkdocs build --strict and deploy.

Principles it instantiates

This stack is a worked example of many atomic principles - copy them, not just the config: Pin GitHub Actions to full commit SHAs, Pin pre-commit hooks to frozen revisions, Pin transitive runtime dependencies, not just the tool, Guard invariants at commit-time, not review-time, Mirror every local guard in CI, Validate config files against their published schema, Enforce the intersection of all renderers and consumers, Grant least-privilege CI permissions at both workflow and job level, Cancel superseded CI runs with a concurrency group, Batch dependency updates with a cooldown, not a firehose, Use PEP 723 inline script metadata for zero-install tooling scripts, Treat warnings as errors (--strict), Track every committed binary type in .gitattributes, Declare formatting once, editor-agnostically, via .editorconfig and Make the build interface a self-documenting Makefile.

Operating manual - the shape, not the repo

The reusable skeleton (details are repo-specific):

  • Bootstrap - one command installs deps + hooks (uv sync && uv run prek install, exposed as make bootstrap).
  • Preview - a live-reloading local server (mkdocs serve / make serve).
  • Multiple entry points - three equally valid contribution paths: a local editor, an optional Obsidian convenience layer over the same folder, and in-browser editing on the host (satisfying Local-first, but not local-required).
  • Conventions the stack imposes - frontmatter title, no second # heading, lowercase-no-whitespace filenames, standard Markdown links (not wiki-links), Excalidraw as portable JSON - each backed by a pre-commit guard.

The following pages link to this page: