Wiki Guide

This wiki is built with Astro 6 and Starlight, hosted on Vercel, and authenticated via Cloudflare Access using Keycloak OIDC. There is no CMS - all content is Markdown or MDX files committed directly to GitHub.

Stack

Item	Detail
Framework	Astro 6 + Starlight
UI components	Starwind UI (supplementary)
Authentication	Cloudflare Access, Keycloak OIDC (wighttrash realm)
Rendering	output: ‘server’
Hosting	Vercel (SSR mode)
Domain	docs.wighttrash.uk
Node.js	22 minimum

How the wiki works

Every page is either a .md or .mdx file under src/content/docs/. Starlight reads these files, renders them with the configured theme and sidebar, and serves them via Vercel.

Pages that contain only text and tables use .md. Pages that use dynamic data from homelab.ts or Starwind UI components use .mdx. The two formats work identically from a content perspective - .mdx just allows component imports.

The sidebar is configured manually in astro.config.mjs. To add a new page to the sidebar, add a link entry to the relevant section. The file must also exist under src/content/docs/ at a matching path.

Editing workflow

There is no browser-based admin interface. All edits are made either directly on GitHub or locally in VS Code.

For simple text edits, editing directly on GitHub works fine. For structural changes, new sections, or anything involving astro.config.mjs, work locally and push.

Editing on GitHub:

Step 1. Navigate to the file in the repo at github.com/wight-trash/.

Step 2. Click the pencil icon to edit.

Step 3. Make changes and commit directly to main.

Step 4. Vercel detects the push and deploys automatically. Build time is around 60-90 seconds.

Editing locally:

Step 1. Pull the latest changes.

git pull origin main

Step 2. Start the development server.

npm run dev

Step 3. Visit http://localhost:4321 to preview changes.

Step 4. Commit and push when ready.

git add .
git commit -m "Describe your change"
git push origin main

Vercel deploys automatically on push to main.

Required frontmatter

Every .md and .mdx file must have at minimum:

---
title: Your Page Title
description: A short description of the page.
---

A missing title will fail the Vercel build. A missing description is permitted but recommended for SEO and the sidebar preview.

Do not add an H1 heading (# Title) to the page body. Starlight renders the title from frontmatter automatically - an H1 in the body creates a duplicate.

Content rules

These apply to every page in this wiki.

No H1 in the body. Start at H2 (##).
No em dashes. Use a hyphen-minus (-) instead.
British English throughout.
No numbered lists for procedures. Use bold step labels with a blank line between each:

**Step 1.** Do this.

**Step 2.** Then do this.

Bold reserved for UI labels and field names only.
Tables for structured reference data.
Code blocks for all commands, config snippets, and file paths.
All external links must open in a new tab. Use the ExternalLink component in .mdx pages, or raw HTML in .md pages if needed.

Guide sections

Page	What it covers
This page	Stack overview, editing workflow, content rules
homelab.ts reference	How the constants file works, how to update it
Components reference	All custom components, when to use them, and how to add new ones