Development

The site is built with Docusaurus and pnpm. It reads every Markdown file of the repos that sit next to this one under the controller directory (READMEs, development notes, and docs/ folders), so every repo has to be cloned next to this one; the build stops with a list of what is missing otherwise. The build also fails on any broken link, anchor, image, or sidebar entry, so each README and note stays correct. This repo's own pages are served from the site root and the controller's README under /controller. Blog posts live in blog/, standalone pages in pages/, and the logo and favicon in static/.

Site configuration

docusaurus.config.ts only hands the configuration to Docusaurus. The configuration itself lives in src/docusaurus/, one file per concern:

File	Contents
config.ts	The Docusaurus Config: site settings, theme, the top navbar (Blog, About, and Repositories), and plugins
sidebars.ts	The left sidebar, which holds this repo and every other repo
slugs.ts	The routes of this repo's pages and of the controller's README
docs-plugin.ts	The docs plugin wrapper that keeps blog/ and pages/ out of the docs
paths.ts	The site and controller directories, and the check that every repo is present
base-url.ts	The path the site is served under (/documentation/).
custom.css	The stylesheet: gray theme, navbar, and full-width blog pages

Everything in this repo that is code is TypeScript: the site configuration, the logo and diagram scripts, and the Prettier configuration (.prettierrc.mts). pnpm run typecheck type-checks them together.

Node.js 26 and pnpm are required: Node runs the TypeScript scripts directly, and the diagram bundle targets Node 26.

pnpm install --frozen-lockfile
pnpm run start   # live preview
pnpm run build   # static output in build/
pnpm run serve   # serve build/ locally

Logo

src/home-lab-logo.mts generates the logo SVG. Node runs it directly, with no build step, and pnpm run logo writes the result to static/home-lab.svg, which provides the site's logo and favicon.

Architecture diagram

infra-architecture.excalidraw is the source of the architecture diagram, and infra-architecture.svg is generated from it with Excalidraw's exportToSvg:

pnpm run diagram           # dark mode, the way the diagram is exported from Excalidraw
pnpm run diagram -- --light

src/excalidraw-to-svg.mts does the conversion. Excalidraw renders through the DOM and is published for bundlers, so the task first bundles the script and Excalidraw with esbuild into node_modules/.cache/diagram/, with jsdom providing the DOM, and then runs the bundle. The fonts the diagram uses are inlined into the SVG from the copy the Excalidraw package ships, so the conversion needs no network, and the output is the same on every run. Edit the diagram in Excalidraw, run the task, and commit both files.

Git hooks

The pre-commit hook runs gitleaks, which must be installed and on PATH. Enable it once per clone:

chmod +x .git-hooks/*
git config --local core.hooksPath .git-hooks