Docs Site¶

This documentation site is self-hosted on the noah cluster. It is built from the same homelab Git repository it documents, using MkDocs Material as the static site generator.

URL — doc.hdhomelab.com
Namespace — misc
Flux manifests — flux/apps/noah/misc/docs-site/
Source — flux branch of homelab repo

How it works¶

The deployment runs three sidecar containers that together form a continuous build pipeline — no CI job, no image builds, no manual deploys:

graph LR
    GS[git-sync\nclones flux branch\nevery 60s]
    BL[builder\nmkdocs build\nevery 60s]
    NG[nginx\nserves /site]
    GIT[(Gitea\nhomelab.git\nflux branch)]
    USER[Browser]

    GIT -->|pull| GS
    GS -->|/git/link| BL
    BL -->|/site| NG
    USER -->|doc.hdhomelab.com| NG

Hold "Alt" / "Option" to enable pan & zoom

Container	Image	Role
`git-sync`	`registry.k8s.io/git-sync/git-sync:v4.4.0`	Clones and continuously syncs the `flux` branch
`builder`	`squidfunk/mkdocs-material:9.7.0`	Builds the static site from the checked-out source
`nginx`	`nginx:alpine`	Serves the built site on port 80

git-sync¶

Polls Gitea every 60 seconds, cloning the flux branch (full depth) into a shared PVC. It writes a stable symlink at /git/link that always points to the latest checkout, so the builder never reads a partial clone.

Credentials (Gitea username + password) are injected from the docs-site-gitea secret via ExternalSecrets.

builder¶

A shell loop that runs mkdocs build every 60 seconds against /git/link. Additional plugins are pip-installed at startup before the loop begins (see Plugins below).

Built output is written to a second shared PVC at /site, which nginx reads directly.

Build latency

End-to-end propagation after a git push to the flux branch is up to ~2 minutes — up to 60s for git-sync to pick up the commit, then up to 60s for the builder loop to re-run.

nginx¶

Serves the static files from the /site PVC on port 80. No custom config — default nginx behaviour. Traffic reaches it via a Gateway API HTTPRoute on the shared gateway. See Networking for gateway details.

Storage¶

Two local-path PVCs, both node-local on worker-3a:

PVC	Size	Mount	Purpose
`docs-site-git-data`	1Gi	`/git`	Git clone (shared by git-sync + builder)
`docs-site-site-data`	500Mi	`/site`	Built static files (shared by builder + nginx)

local-path is used here because latency doesn't matter for a static file serve, and the data is fully reproducible from Git — no durability concern. See Storage for storage class details.

Networking¶

doc.hdhomelab.com → shared gateway (infra) → docs-site:80 → nginx

The HTTPRoute is in the misc namespace, referencing the shared gateway in infra.

Secrets¶

Secret	Vault path	Keys	Purpose
`docs-site-gitea`	`docs-site/gitea`	`username`, `password`	Authenticates git-sync to Gitea

Plugins¶

Four plugins extend the base MkDocs Material install.

search¶

Built-in Material plugin, customised with an extended token separator so camelCase identifiers, punctuation, and Unicode zero-width spaces are all split into searchable tokens. Enables the top-right search bar.

document-dates¶

mkdocs-document-dates — appends last-modified metadata to the bottom of every page, formatted as a relative timestamp (e.g. 3 days ago) with the absolute date on hover.

document-dates:
  position: bottom
  type: timeago
  date_format: '%B %d, %Y'
  time_format: '%H:%M:%S UTC'

glightbox¶

mkdocs-glightbox — wraps every image in a lightbox overlay. Clicking any image opens it full-screen with zoom and pan, without any per-image markup changes.

panzoom¶

mkdocs-panzoom-plugin — adds pinch-to-zoom and drag-to-pan to Mermaid diagrams. Enabled with full_screen: true so diagrams can be expanded to fill the viewport.

panzoom:
  full_screen: true

Build hook¶

docs/hooks/hooks.py is a lightweight MkDocs event hook registered in mkdocs.yml. It sets the copyright footer dynamically so the year never goes stale:

def on_config(config):
    config.copyright = f"Copyright &copy; {datetime.now().year} HD Homelab"

Source¶

The site sources are in the homelab repo:

mkdocs.yml              # Site config and nav
docs/
├── infrastructure/
├── applications/
├── monitoring/
├── patterns/
├── onboarding/
├── hooks/              # MkDocs build hooks
├── overrides/          # Theme overrides
└── stylesheets/        # Custom CSS

The site is rebuilt from the flux branch — not main. Docs changes only go live once merged (or committed) to flux. See GitOps for the branch strategy.