BlumeOps Docs

Update Documentation

3 min read

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:

TypeDirectoryDescription
featurefeature/New features
bugfixbugfix/Bug fixes
infrainfra/Infrastructure changes
docdoc/Documentation updates
aiai/AI assistance changes
miscmisc/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
  • docs - Documentation service reference
  • forgejo - Git forge and CI/CD
  • argocd - GitOps deployment

Graph View

Backlinks