From 6289da7a47bbf91f2cb4fd2fa61d51b8f129b67e Mon Sep 17 00:00:00 2001
From: Erich Blume <blume.erich@gmail.com>
Date: Tue, 3 Feb 2026 20:16:24 -0800
Subject: [PATCH] Add how-to guide for updating documentation

Covers the build-blumeops workflow, towncrier changelog fragments,
Quartz static site generator, and the k8s runner environment.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/how-to/index.md                |   6 ++
 docs/how-to/update-documentation.md | 130 ++++++++++++++++++++++++++++
 2 files changed, 136 insertions(+)
 create mode 100644 docs/how-to/update-documentation.md

diff --git a/docs/how-to/index.md b/docs/how-to/index.md
index 418d551..6f1a29a 100644
--- a/docs/how-to/index.md
+++ b/docs/how-to/index.md
@@ -21,6 +21,12 @@ Task-oriented instructions for common BlumeOps operations. These guides assume y
 |-------|-------------|
 | [[update-tailscale-acls]] | Update Tailscale access control policies |
 
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [[update-documentation]] | Publish docs via build-blumeops workflow |
+
 ## Operations
 
 | Guide | Description |
diff --git a/docs/how-to/update-documentation.md b/docs/how-to/update-documentation.md
new file mode 100644
index 0000000..be47f5e
--- /dev/null
+++ b/docs/how-to/update-documentation.md
@@ -0,0 +1,130 @@
+---
+title: update-documentation
+tags:
+  - how-to
+  - documentation
+  - ci-cd
+---
+
+# Update Documentation
+
+How to publish documentation changes to https://docs.ops.eblu.me.
+
+## Quick Release
+
+After merging documentation changes to main:
+
+1. Go to **Actions** > **Build BlumeOps** > **Run workflow**
+2. Enter a version (e.g., `v1.2.0`) or leave empty to auto-increment
+3. The workflow builds, releases, and deploys automatically
+
+Direct link: https://forge.ops.eblu.me/eblume/blumeops/actions?workflow=build-blumeops.yaml
+
+## What the Workflow Does
+
+The `build-blumeops` workflow (`.forgejo/workflows/build-blumeops.yaml`):
+
+1. **Resolves version** - Uses input or auto-increments from latest release
+2. **Builds changelog** - Runs towncrier to collect changelog fragments
+3. **Builds docs** - Clones Quartz, builds static site from `docs/`
+4. **Creates release** - Uploads `docs-<version>.tar.gz` to Forgejo releases
+5. **Updates deployment** - Edits `argocd/manifests/docs/deployment.yaml` with new URL
+6. **Commits changes** - Pushes changelog and deployment updates to main
+7. **Deploys** - Syncs the `docs` ArgoCD app
+
+## Changelog Fragments (Towncrier)
+
+When making changes, add a changelog fragment to `docs/changelog.d/`:
+
+```bash
+# Format: <identifier>.<type>.md
+# Types: feature, bugfix, infra, doc, misc
+
+# Using branch name (preferred)
+echo "Add new feature X" > docs/changelog.d/my-feature.feature.md
+
+# Orphan fragment (when no branch fits)
+echo "Fix bug Y" > docs/changelog.d/+fix-bug.bugfix.md
+```
+
+Fragments are automatically collected into `docs/CHANGELOG.md` during release.
+
+**Fragment types:**
+| Type | Directory | Description |
+|------|-----------|-------------|
+| `feature` | `feature/` | New features |
+| `bugfix` | `bugfix/` | Bug fixes |
+| `infra` | `infra/` | Infrastructure changes |
+| `doc` | `doc/` | Documentation updates |
+| `misc` | `misc/` | Other (content hidden in changelog) |
+
+## Runner Environment
+
+The workflow runs on the `k8s` label, which uses the [[forgejo]]-runner in Kubernetes:
+
+- **Runner deployment**: `argocd/manifests/forgejo-runner/`
+- **Job image**: `registry.ops.eblu.me/blumeops/forgejo-runner:latest`
+- **Includes**: Node.js 24, npm, git, jq, Docker CLI, uv/uvx, argocd CLI
+
+The job image is built from `containers/forgejo-runner/Dockerfile`.
+
+## Quartz Static Site Generator
+
+[Quartz](https://quartz.jzhao.xyz/) builds the documentation into a static site with:
+- Wiki-link support (`[[page]]` syntax)
+- Backlinks panel showing what references each page
+- Graph view of document connections
+- Full-text search
+
+**Configuration files** (in `docs/`):
+- `quartz.config.ts` - Site metadata, plugins, theme
+- `quartz.layout.ts` - Page layout components
+
+Quartz is cloned fresh during each build (not vendored) to use the latest version.
+
+## Manual Build (Local)
+
+To test docs locally without triggering a release:
+
+```bash
+# Clone Quartz
+git clone --depth 1 https://github.com/jackyzha0/quartz.git /tmp/quartz
+cd /tmp/quartz
+
+# Install dependencies
+npm ci
+
+# Copy config and content
+cp /path/to/blumeops/docs/quartz.config.ts .
+cp /path/to/blumeops/docs/quartz.layout.ts .
+rm -rf content
+cp -r /path/to/blumeops/docs content
+
+# Build
+npx quartz build
+
+# Serve locally
+npx quartz build --serve
+```
+
+## Troubleshooting
+
+**Workflow fails on "Resolve version":**
+- Check if the version already exists as a release
+- Ensure version format is `vX.Y.Z`
+
+**Docs not updating after deploy:**
+- Check ArgoCD sync status: `argocd app get docs`
+- Verify the pod restarted: `kubectl --context=minikube-indri -n docs get pods`
+- Check pod logs for download errors
+
+**Towncrier not finding fragments:**
+- Fragments must be in `docs/changelog.d/`
+- Must have `.md` extension
+- Must match pattern `<name>.<type>.md`
+
+## Related
+
+- [[docs]] - Documentation service reference
+- [[forgejo]] - Git forge and CI/CD
+- [[argocd]] - GitOps deployment