Erich Blume b197bd5f58 Adopt Dagger CI for docs build (Phase 2) (#157 )

## Summary

Migrates the docs build pipeline to Dagger (Phase 2 of the Dagger CI adoption plan).

- **Backfill `date-modified` frontmatter** on all 80 docs — Dagger's `--src=.` excludes `.git`, so Quartz can't use git history for page dates. Frontmatter dates work with or without git.
- **New `docs-check-frontmatter` mise task + pre-commit hook** — validates all docs have `title`, `tags`, and `date-modified`
- **New Dagger functions** — `build_changelog` (towncrier in Python container) and `build_docs` (chains changelog → Quartz build in Node container, returns tarball)
- **Simplified CI workflow** — the ~44-line inline Quartz build (clone, npm ci, build, tar, cleanup) is replaced by `dagger call build-docs`. Changelog step remains local on the runner since towncrier needs to modify the host working tree for the git commit.

### Design decisions

- **Towncrier runs twice in CI**: once inside Dagger (for the docs tarball) and once on the runner (for the git commit). This is intentional — Dagger's directory export is additive and can't delete the consumed changelog fragments from the host.
- **Artifact hosting stays on Forgejo Releases** (not migrated to Forgejo Packages as the plan doc originally suggested). That migration can happen independently.
- **`date-modified` frontmatter** preserved even though `build_changelog` installs git — the git there is only for towncrier's `git add` call, not for history. The local iteration story (`dagger call build-docs --src=. --version=dev` with uncommitted changes) depends on frontmatter dates.

### Local iteration

```bash
dagger call build-docs --src=. --version=dev export --path=./docs-dev.tar.gz
tar tf docs-dev.tar.gz | head -20
```

## Deployment and Testing

- [x] `dagger call build-docs --src=. --version=dev` produces valid 1.1MB tarball (149 HTML pages)
- [x] Pre-commit hooks pass (including new `docs-check-frontmatter`)
- [ ] Full `workflow_dispatch` run after merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/157

2026-02-11 16:33:16 -08:00

3.3 KiB

Raw Blame History

title

date-modified

Exploring the Documentation

Audiences: All (Owner, AI, Reader, Contributor, Replicator)

This guide explains how the BlumeOps documentation is organized and how to find what you need.

Documentation Structure

The docs follow the Diataxis framework:

Section	Purpose	When to Use
**[[tutorials	Tutorials]]**	Learning-oriented
**[[reference	Reference]]**	Information-oriented
**[[how-to	How-to]]**	Task-oriented
**[[plans	Plans]]**	Future work
**[[explanation	Explanation]]**	Understanding-oriented

Quick Paths by Audience

For Erich (Owner)

You probably want quick access to operational details:

how-to guides for common operations (deploy, troubleshoot, update ACLs)
plans captures migration and transition plans for future execution
reference has service URLs, commands, and config locations
ai-assistance-guide explains how to work effectively with Claude
Run mise run zk-docs to prime AI context with key documentation

For Claude/AI Agents

Context for effective assistance:

Read ai-assistance-guide for operational conventions
plans has migration plans designed for AI-executed sessions
reference has the technical specifics you'll need
The repo's CLAUDE.md has critical rules (especially the kubectl context requirement)

For External Readers

Understanding what this is:

explanation covers the "why" behind design decisions
reference shows what's actually running
Browse service pages to see specific implementations

For Contributors

Getting started with changes:

contributing walks through the workflow
how-to guides for specific tasks (deploy services, add roles)
reference tells you where things live

For Replicators

Replicators are people who want to build their own similar homelab GitOps setup, using BlumeOps as inspiration.

replicating-blumeops provides the overview, with linked tutorials that go deep on individual components
explanation covers architecture and design rationale
Reference pages show specific configuration choices

Using Wiki Links

Documentation uses [[wiki-links]] for cross-references:

[[service-name]] links to a reference page
[[page|Display Text]] customizes the link text

When reading on the web (docs.eblu.me), these render as clickable links. The backlinks panel shows what references each page.

Pre-commit hooks automatically validate that all wiki-links point to existing files and that link targets are unambiguous.

AI Context Priming

The zk-docs mise task concatenates key documentation files for AI context:

mise run zk-docs -- --style=header --color=never --decorations=always

This outputs the AI assistance guide, reference index, how-to index, architecture overview, and tutorials index - providing Claude with essential context for BlumeOps operations.

tutorials - Parent index of all tutorials
update-documentation - How to publish doc changes
review-documentation - Periodic doc review process

3.3 KiB Raw Blame History