blumeops/docs/how-to/update-documentation.md

title	modified	tags
Update Documentation	2026-02-08	how-to documentation ci-cd

Update Documentation

How to publish documentation changes to https://docs.eblu.me.

Quick Release

After merging documentation changes to main:

1. Go to Actions > Build BlumeOps > Run workflow
2. Select version bump type (patch/minor/major) or enter a specific version
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/:

# Format: <identifier>.<type>.md
# Types: feature, bugfix, infra, doc, ai, 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 CHANGELOG.md (at repo root) during release.

Fragment types:

Type	Directory	Description
feature	feature/	New features
bugfix	bugfix/	Bug fixes
infra	infra/	Infrastructure changes
doc	doc/	Documentation updates
ai	ai/	AI assistance changes
misc	misc/	Other changes

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 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:

# 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