Skip to content

This Docs Site

This is how I made docs.saxobroko.com.

Stack

  • Material for MkDocs for the theme and layout
  • GitHub for source control at saxobroko/SaxDocs
  • GitHub Actions to build the site on every push to main
  • Cloudflare Pages to host the built site at docs.saxobroko.com

The old setup ran MkDocs on the home PC and proxied it through NPM. That meant the docs only worked when the PC was on. Cloudflare Pages serves the static files from Cloudflare's edge instead, so the site stays up even when home is offline.

Folder structure

The nav bar follows the folder structure under docs/:

docs/
├── Server/       # NAS, network, media
├── PC/           # Client PC notes + app docs (services run on TrueNAS)
├── External/     # Cloudflare, Yubikey, outside services
├── Finance/      # Money stuff
├── Personal/     # Everything else
└── index.md      # Landing page

MkDocs picks up pages from folders automatically through the awesome-pages plugin. Top-level tabs (Server, PC, Finance, Personal, External) and sidebar sections are configured in each folder's .pages file and docs/.pages.

Theme and navigation

  • Material for MkDocs — default styling with minimal overrides in overrides/assets/stylesheets/extra.css
  • Left sidebar — full site tree, always visible (no top tabs)
  • Right sidebar — on-page table of contents
  • Colours — muted grey accents, header matches page background
  • Nav order is controlled by each folder's .pages file

Editing locally

Install dependencies and preview:

pip install -r requirements.txt
mkdocs serve

Or use Docker:

docker compose up

That runs MkDocs Material on port 8000. Open http://localhost:8000 to preview changes before pushing.

Deploying changes

  1. Edit markdown files in the docs/ folder
  2. Commit and push to main
  3. GitHub Actions runs mkdocs build and uploads the site/ folder to Cloudflare Pages
  4. The site updates at docs.saxobroko.com within a minute or two

If the live site looks stale, check the Actions tab on GitHub for a failed build.

Full Cloudflare setup steps (one-time) are in Cloudflare Pages.

Adding a new page

  1. Create a .md file in the right folder
  2. Link to it from related pages so it's discoverable
  3. Push to main
  4. The page shows up in the nav automatically

Page history

Every doc page shows when it was created and last updated at the bottom of the page. Dates come from git commit history via the git-revision-date-localized plugin (Melbourne time, relative "time ago" format).

To dig deeper into changes for a specific page:

  1. On the page — use the history icon at the top of the article (next to "View source") or the View history / Blame links in the page footer. Both open the matching file on GitHub.
  2. Commit history — View history lists every commit that touched that markdown file.
  3. Line-by-line blame — Blame shows which commit last changed each line.

Example for this page:

CI checks out the full git history (fetch-depth: 0) so production builds get accurate dates. Local previews need a normal git clone (not a shallow checkout) for the same accuracy.