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

.dagger/src/blumeops_ci/main.py

@@ -1,5 +1,5 @@
 import dagger
-from dagger import function, object_type
+from dagger import dag, function, object_type
 
 
 @object_type
@@ -22,3 +22,65 @@ class BlumeopsCi:
         ctr = self.build(src, container_name)
         ref = f"{registry}/blumeops/{container_name}:{version}"
         return await ctr.publish(ref)
+
+    @function
+    async def build_changelog(
+        self, src: dagger.Directory, version: str
+    ) -> dagger.Directory:
+        """Run towncrier to build changelog, return modified source tree."""
+        return await (
+            dag.container()
+            .from_("python:3.12-slim")
+            # git is required because towncrier stages CHANGELOG.md via git add
+            .with_exec(["apt-get", "update", "-qq"])
+            .with_exec(["apt-get", "install", "-y", "-qq", "git"])
+            .with_exec(["pip", "install", "towncrier"])
+            .with_directory("/workspace", src)
+            .with_workdir("/workspace")
+            .with_exec(["git", "init"])
+            .with_exec(["towncrier", "build", "--version", version, "--yes"])
+            .directory("/workspace")
+        )
+
+    @function
+    async def build_docs(self, src: dagger.Directory, version: str) -> dagger.File:
+        """Build changelog then Quartz site. Returns docs tarball."""
+        updated_src = await self.build_changelog(src, version)
+        return await (
+            dag.container()
+            .from_("node:20-slim")
+            .with_exec(["apt-get", "update", "-qq"])
+            .with_exec(["apt-get", "install", "-y", "-qq", "git"])
+            .with_directory("/workspace", updated_src)
+            .with_workdir("/workspace")
+            .with_exec(
+                [
+                    "git",
+                    "clone",
+                    "--depth=1",
+                    "https://github.com/jackyzha0/quartz.git",
+                    "/tmp/quartz",
+                ]
+            )
+            .with_exec(
+                [
+                    "sh",
+                    "-c",
+                    "cp -r /tmp/quartz/quartz /tmp/quartz/package*.json "
+                    "/tmp/quartz/tsconfig.json .",
+                ]
+            )
+            .with_exec(["npm", "ci"])
+            .with_exec(["cp", "docs/quartz.config.ts", "."])
+            .with_exec(["cp", "docs/quartz.layout.ts", "."])
+            .with_exec(["cp", "CHANGELOG.md", "docs/"])
+            .with_exec(["npx", "quartz", "build", "-d", "docs"])
+            .with_exec(
+                [
+                    "sh",
+                    "-c",
+                    f"tar -czf /docs-{version}.tar.gz -C public .",
+                ]
+            )
+            .file(f"/docs-{version}.tar.gz")
+        )

.forgejo/workflows/build-blumeops.yaml

@@ -106,14 +106,43 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          # Need full history for git operations
           fetch-depth: 0
 
+      - name: Ensure Dagger CLI
+        run: |
+          # Bootstrap: install dagger if not already in the runner image.
+          # Remove once all runners include dagger (Phase 3).
+          if ! command -v dagger &>/dev/null; then
+            echo "Dagger not found, installing..."
+            curl -fsSL https://dl.dagger.io/dagger/install.sh | DAGGER_VERSION=0.19.11 sh
+            mv ./bin/dagger /usr/local/bin/dagger && rmdir ./bin
+          fi
+          dagger version
+
+      - name: Build docs
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          TARBALL="docs-${VERSION}.tar.gz"
+          echo "Building docs via Dagger..."
+          # build-docs calls build_changelog internally (towncrier runs inside
+          # the Dagger container). The host working tree is not modified — only
+          # the tarball is exported. Towncrier runs a second time on the runner
+          # in the next step so that CHANGELOG.md and fragment deletion are
+          # captured in the git commit.
+          dagger call build-docs --src=. --version="$VERSION" \
+            export --path="./$TARBALL"
+          echo "Build complete!"
+          ls -lh "$TARBALL"
+
       - name: Build changelog
         id: changelog
         run: |
           VERSION="${{ steps.version.outputs.version }}"
 
+          # Run towncrier on the runner (not in Dagger) so that CHANGELOG.md
+          # updates and fragment deletions appear in the working tree for the
+          # git commit step. This is intentionally a second towncrier run —
+          # the first happened inside the Dagger build-docs container above.
           # Check if there are any changelog fragments
           FRAGMENTS=$(find docs/changelog.d -name "*.md" -not -name ".gitkeep" 2>/dev/null | wc -l)
 
@@ -123,7 +152,6 @@ jobs:
             echo "changelog_updated=true" >> "$GITHUB_OUTPUT"
 
             # Extract the changelog section for this release to include in release body
-            # The section starts with "## [$VERSION]" and ends before the next "## [" or EOF
             RELEASE_NOTES=$(awk -v ver="$VERSION" '
               /^## \[/ {
                 if (found) exit
@@ -132,7 +160,6 @@ jobs:
               found {print}
             ' CHANGELOG.md | tail -n +2)
 
-            # Save release notes to a file for later use (handles multiline content)
             echo "$RELEASE_NOTES" > /tmp/release_notes.md
             echo "Release notes extracted for $VERSION"
           else
@@ -141,51 +168,6 @@ jobs:
             echo "" > /tmp/release_notes.md
           fi
 
-      - name: Build docs
-        run: |
-          VERSION="${{ steps.version.outputs.version }}"
-          echo "Node version: $(node --version)"
-          echo "NPM version: $(npm --version)"
-
-          # Clone Quartz to temp location
-          git clone --depth 1 https://github.com/jackyzha0/quartz.git /tmp/quartz
-
-          # Copy Quartz build system into blumeops workspace
-          # This allows building from within the repo so git can find file history
-          cp -r /tmp/quartz/quartz "$GITHUB_WORKSPACE/"
-          cp /tmp/quartz/package.json "$GITHUB_WORKSPACE/"
-          cp /tmp/quartz/package-lock.json "$GITHUB_WORKSPACE/"
-          cp /tmp/quartz/tsconfig.json "$GITHUB_WORKSPACE/"
-
-          cd "$GITHUB_WORKSPACE"
-
-          # Install dependencies
-          npm ci
-
-          # Copy our configuration to workspace root
-          cp docs/quartz.config.ts .
-          cp docs/quartz.layout.ts .
-
-          # Copy CHANGELOG.md into docs so it's part of the content
-          cp CHANGELOG.md docs/
-
-          # Build using -d docs so git can find file history at correct paths
-          echo "Building static site..."
-          npx quartz build -d docs
-
-          # Create tarball
-          TARBALL="docs-${VERSION}.tar.gz"
-          echo "Creating tarball: $TARBALL"
-          tar -czf "$TARBALL" -C public .
-
-          echo "Build complete!"
-          ls -lh "$TARBALL"
-
-          # Clean up Quartz build artifacts (keep tarball)
-          rm -rf quartz public node_modules
-          rm -f package.json package-lock.json tsconfig.json quartz.config.ts quartz.layout.ts
-          rm -f docs/CHANGELOG.md  # Remove copied file
-
       - name: Create release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.pre-commit-config.yaml

@@ -110,3 +110,9 @@ repos:
         language: system
         files: ^docs/.*\.md$
         pass_filenames: false
+      - id: docs-check-frontmatter
+        name: docs-check-frontmatter
+        entry: mise run docs-check-frontmatter
+        language: system
+        files: ^docs/.*\.md$
+        pass_filenames: false

docs/changelog.d/dagger-phase2-docs.feature.md

@@ -0,0 +1 @@
+Migrate docs build pipeline to Dagger (Phase 2): `dagger call build-docs --src=. --version=dev` now runs the full Quartz build locally, identically to CI. Adds `date-modified` frontmatter to all docs and a `docs-check-frontmatter` pre-commit hook.

docs/explanation/architecture.md

@@ -1,5 +1,6 @@
 ---
 title: Architecture
+date-modified: 2026-02-09
 last-reviewed: 2026-02-09
 tags:
   - explanation

docs/explanation/explanation.md

@@ -1,5 +1,6 @@
 ---
 title: Explanation
+date-modified: 2026-02-10
 last-reviewed: 2026-02-10
 tags:
   - explanation

docs/explanation/security-model.md

@@ -1,5 +1,6 @@
 ---
 title: Security Model
+date-modified: 2026-02-11
 last-reviewed: 2026-02-11
 tags:
   - explanation

docs/explanation/why-gitops.md

@@ -1,5 +1,6 @@
 ---
 title: Why GitOps
+date-modified: 2026-02-07
 tags:
   - explanation
   - philosophy

docs/how-to/add-ansible-role.md

@@ -1,5 +1,6 @@
 ---
 title: Add Ansible Role
+date-modified: 2026-02-07
 tags:
   - how-to
   - ansible

docs/how-to/deploy-k8s-service.md

@@ -1,5 +1,6 @@
 ---
 title: Deploy K8s Service
+date-modified: 2026-02-07
 tags:
   - how-to
   - kubernetes

docs/how-to/expose-service-publicly.md

@@ -1,5 +1,6 @@
 ---
 title: Expose a Service Publicly
+date-modified: 2026-02-08
 tags:
   - how-to
   - fly-io

docs/how-to/gandi-operations.md

@@ -1,5 +1,6 @@
 ---
 title: Gandi Operations
+date-modified: 2026-02-08
 tags:
   - how-to
   - dns

docs/how-to/how-to.md

@@ -1,5 +1,6 @@
 ---
 title: How-To
+date-modified: 2026-02-11
 tags:
   - how-to
 ---

docs/how-to/knowledgebase/review-documentation.md

@@ -1,5 +1,6 @@
 ---
 title: Review Documentation
+date-modified: 2026-02-09
 tags:
   - how-to
   - documentation

docs/how-to/manage-flyio-proxy.md

@@ -1,5 +1,6 @@
 ---
 title: Manage Fly.io Proxy
+date-modified: 2026-02-08
 tags:
   - how-to
   - fly-io

docs/how-to/plans/add-unifi-pulumi-stack.md

@@ -1,5 +1,6 @@
 ---
 title: "Plan: Add UniFi Pulumi Stack"
+date-modified: 2026-02-11
 tags:
   - how-to
   - plans

docs/how-to/plans/adopt-dagger-ci.md

@@ -1,5 +1,6 @@
 ---
 title: "Plan: Adopt Dagger as CI/CD Build Engine"
+date-modified: 2026-02-11
 tags:
   - how-to
   - plans
@@ -9,7 +10,7 @@ tags:
 
 # Plan: Adopt Dagger as CI/CD Build Engine
 
-> **Status:** Phase 1 implemented
+> **Status:** Phase 2 implemented
 
 ## Background
 
@@ -496,11 +497,11 @@ BuildKit caches aggressively, making repeated builds fast. Since the Forgejo run
 - [x] Existing `mise run container-tag-and-release` workflow still works end-to-end
 
 ### Phase 2 (Docs)
-- [ ] `dagger call build-docs --src=. --version=dev` produces valid tarball locally
-- [ ] Tarball contents match current Quartz build output
-- [ ] `dagger call release-docs` uploads to Forgejo packages successfully
-- [ ] Quartz container starts and serves docs from Forgejo packages URL
-- [ ] ArgoCD sync works from within Dagger
+- [x] `dagger call build-docs --src=. --version=dev` produces valid tarball locally
+- [x] Tarball contents match current Quartz build output
+- [ ] ~~`dagger call release-docs` uploads to Forgejo packages successfully~~ (deferred — artifact hosting stays on Forgejo Releases)
+- [ ] ~~Quartz container starts and serves docs from Forgejo packages URL~~ (deferred)
+- [ ] ~~ArgoCD sync works from within Dagger~~ (deferred)
 - [ ] Forgejo Actions workflow_dispatch completes full release cycle
 - [ ] CHANGELOG.md and fragment cleanup committed correctly
 

docs/how-to/plans/adopt-oidc-provider.md

@@ -1,5 +1,6 @@
 ---
 title: "Plan: Adopt OIDC Identity Provider"
+date-modified: 2026-02-11
 tags:
   - how-to
   - plans

docs/how-to/plans/forgejo-actions-dashboard.md

@@ -1,5 +1,6 @@
 ---
 title: "Plan: Forgejo Actions Dashboard"
+date-modified: 2026-02-11
 tags:
   - how-to
   - plans

docs/how-to/plans/harden-zot-registry.md

@@ -1,5 +1,6 @@
 ---
 title: "Plan: Harden Zot Registry"
+date-modified: 2026-02-11
 tags:
   - how-to
   - plans

docs/how-to/plans/migrate-forgejo-from-brew.md

@@ -1,5 +1,6 @@
 ---
 title: "Plan: Migrate Forgejo from Brew to Source Build"
+date-modified: 2026-02-10
 tags:
   - how-to
   - plans

docs/how-to/plans/operationalize-reolink-camera.md

@@ -1,5 +1,6 @@
 ---
 title: "Plan: Operationalize ReoLink Camera"
+date-modified: 2026-02-11
 tags:
   - how-to
   - plans

docs/how-to/plans/plans.md

@@ -1,5 +1,6 @@
 ---
 title: Plans
+date-modified: 2026-02-11
 tags:
   - how-to
   - plans

docs/how-to/plans/upstream-fork-strategy.md

@@ -1,5 +1,6 @@
 ---
 title: "Plan: Upstream Fork Strategy"
+date-modified: 2026-02-11
 tags:
   - how-to
   - plans

docs/how-to/restart-indri.md

@@ -1,5 +1,6 @@
 ---
 title: Restart Indri
+date-modified: 2026-02-10
 tags:
   - how-to
   - operations

docs/how-to/restore-1password-backup.md

@@ -1,5 +1,6 @@
 ---
 title: Restore 1Password Backup
+date-modified: 2026-02-10
 tags:
   - how-to
   - operations

docs/how-to/troubleshooting.md

@@ -1,5 +1,6 @@
 ---
 title: Troubleshooting
+date-modified: 2026-02-07
 tags:
   - how-to
   - operations

docs/how-to/update-documentation.md

@@ -1,5 +1,6 @@
 ---
 title: Update Documentation
+date-modified: 2026-02-08
 tags:
   - how-to
   - documentation

docs/how-to/update-tailscale-acls.md

@@ -1,5 +1,6 @@
 ---
 title: Update Tailscale ACLs
+date-modified: 2026-02-07
 tags:
   - how-to
   - tailscale

docs/how-to/use-pypi-proxy.md

@@ -1,5 +1,6 @@
 ---
 title: Use PyPI Proxy
+date-modified: 2026-02-07
 tags:
   - how-to
   - python

docs/index.md

@@ -1,5 +1,6 @@
 ---
 title: BlumeOps
+date-modified: 2026-02-08
 aliases: []
 id: index
 tags: []

docs/reference/ansible/roles.md

@@ -1,5 +1,6 @@
 ---
 title: Roles
+date-modified: 2026-02-07
 tags:
   - ansible
   - reference

docs/reference/infrastructure/gandi.md

@@ -1,5 +1,6 @@
 ---
 title: Gandi
+date-modified: 2026-02-08
 tags:
   - infrastructure
   - networking

docs/reference/infrastructure/gilbert.md

@@ -1,5 +1,6 @@
 ---
 title: Gilbert
+date-modified: 2026-02-07
 tags:
   - infrastructure
   - host

docs/reference/infrastructure/hosts.md

@@ -1,5 +1,6 @@
 ---
 title: Hosts
+date-modified: 2026-02-10
 tags:
   - infrastructure
 ---

docs/reference/infrastructure/indri.md

@@ -1,5 +1,6 @@
 ---
 title: Indri
+date-modified: 2026-02-09
 tags:
   - infrastructure
   - host

docs/reference/infrastructure/power.md

@@ -1,5 +1,6 @@
 ---
 title: Power
+date-modified: 2026-02-09
 tags:
   - infrastructure
 ---

docs/reference/infrastructure/routing.md

@@ -1,5 +1,6 @@
 ---
 title: Routing
+date-modified: 2026-02-09
 tags:
   - infrastructure
   - networking

docs/reference/infrastructure/tailscale.md

@@ -1,5 +1,6 @@
 ---
 title: Tailscale
+date-modified: 2026-02-08
 tags:
   - infrastructure
   - networking

docs/reference/infrastructure/unifi.md

@@ -1,5 +1,6 @@
 ---
 title: UniFi
+date-modified: 2026-02-10
 tags:
   - infrastructure
   - networking

docs/reference/kubernetes/apps.md

@@ -1,5 +1,6 @@
 ---
 title: Apps
+date-modified: 2026-02-07
 tags:
   - kubernetes
   - argocd

docs/reference/kubernetes/cluster.md

@@ -1,5 +1,6 @@
 ---
 title: Cluster
+date-modified: 2026-02-07
 tags:
   - kubernetes
 ---

docs/reference/kubernetes/external-secrets.md

@@ -1,5 +1,6 @@
 ---
 title: External Secrets
+date-modified: 2026-02-07
 tags:
   - kubernetes
   - secrets

docs/reference/kubernetes/tailscale-operator.md

@@ -1,5 +1,6 @@
 ---
 title: Tailscale Operator
+date-modified: 2026-02-08
 tags:
   - kubernetes
   - tailscale

docs/reference/operations/backup.md

@@ -1,5 +1,6 @@
 ---
 title: Backup
+date-modified: 2026-02-07
 tags:
   - operations
 ---

docs/reference/operations/disaster-recovery.md

@@ -1,5 +1,6 @@
 ---
 title: Disaster Recovery
+date-modified: 2026-02-10
 tags:
   - operations
 ---

docs/reference/operations/observability.md

@@ -1,5 +1,6 @@
 ---
 title: Observability
+date-modified: 2026-02-07
 tags:
   - operations
 ---

docs/reference/reference.md

@@ -1,5 +1,6 @@
 ---
 title: Reference
+date-modified: 2026-02-10
 tags:
   - reference
 ---

docs/reference/services/1password.md

@@ -1,5 +1,6 @@
 ---
 title: 1Password
+date-modified: 2026-02-10
 tags:
   - service
   - secrets

docs/reference/services/alloy.md

@@ -1,5 +1,6 @@
 ---
 title: Alloy
+date-modified: 2026-02-08
 tags:
   - service
   - observability

docs/reference/services/argocd.md

@@ -1,5 +1,6 @@
 ---
 title: ArgoCD
+date-modified: 2026-02-07
 tags:
   - service
   - gitops

docs/reference/services/automounter.md

@@ -1,5 +1,6 @@
 ---
 title: Automounter
+date-modified: 2026-02-07
 tags:
   - services
   - macos

docs/reference/services/borgmatic.md

@@ -1,5 +1,6 @@
 ---
 title: Borgmatic
+date-modified: 2026-02-10
 tags:
   - service
   - backup

docs/reference/services/caddy.md

@@ -1,5 +1,6 @@
 ---
 title: Caddy
+date-modified: 2026-02-08
 tags:
   - service
   - networking

docs/reference/services/devpi.md

@@ -1,5 +1,6 @@
 ---
 title: Devpi
+date-modified: 2026-02-07
 tags:
   - service
   - python

docs/reference/services/docs.md

@@ -1,5 +1,6 @@
 ---
 title: Docs
+date-modified: 2026-02-08
 tags:
   - service
   - documentation

docs/reference/services/flyio-proxy.md

@@ -1,5 +1,6 @@
 ---
 title: Fly.io Proxy
+date-modified: 2026-02-08
 tags:
   - service
   - networking

docs/reference/services/forgejo.md

@@ -1,5 +1,6 @@
 ---
 title: Forgejo
+date-modified: 2026-02-08
 tags:
   - service
   - git

docs/reference/services/grafana.md

@@ -1,5 +1,6 @@
 ---
 title: Grafana
+date-modified: 2026-02-08
 tags:
   - service
   - observability

docs/reference/services/immich.md

@@ -1,5 +1,6 @@
 ---
 title: Immich
+date-modified: 2026-02-07
 tags:
   - service
   - media

docs/reference/services/jellyfin.md

@@ -1,5 +1,6 @@
 ---
 title: Jellyfin
+date-modified: 2026-02-07
 tags:
   - service
   - media

docs/reference/services/kiwix.md

@@ -1,5 +1,6 @@
 ---
 title: Kiwix
+date-modified: 2026-02-07
 tags:
   - service
   - knowledge

docs/reference/services/loki.md

@@ -1,5 +1,6 @@
 ---
 title: Loki
+date-modified: 2026-02-08
 tags:
   - service
   - observability

docs/reference/services/miniflux.md

@@ -1,5 +1,6 @@
 ---
 title: Miniflux
+date-modified: 2026-02-07
 tags:
   - service
   - rss

docs/reference/services/navidrome.md

@@ -1,5 +1,6 @@
 ---
 title: Navidrome
+date-modified: 2026-02-07
 tags:
   - service
   - media

docs/reference/services/postgresql.md

@@ -1,5 +1,6 @@
 ---
 title: PostgreSQL
+date-modified: 2026-02-07
 tags:
   - service
   - database

docs/reference/services/prometheus.md

@@ -1,5 +1,6 @@
 ---
 title: Prometheus
+date-modified: 2026-02-08
 tags:
   - service
   - observability

docs/reference/services/teslamate.md

@@ -1,5 +1,6 @@
 ---
 title: TeslaMate
+date-modified: 2026-02-07
 tags:
   - service
   - vehicle

docs/reference/services/transmission.md

@@ -1,5 +1,6 @@
 ---
 title: Transmission
+date-modified: 2026-02-07
 tags:
   - service
   - torrent

docs/reference/services/zot.md

@@ -1,5 +1,6 @@
 ---
 title: Zot
+date-modified: 2026-02-07
 tags:
   - service
   - registry

docs/reference/storage/backups.md

@@ -1,5 +1,6 @@
 ---
 title: Backups
+date-modified: 2026-02-10
 tags:
   - storage
   - backup

docs/reference/storage/postgresql-storage.md

@@ -1,5 +1,6 @@
 ---
 title: PostgreSQL Storage
+date-modified: 2026-02-07
 tags:
   - storage
   - database

docs/reference/storage/sifaka.md

@@ -1,5 +1,6 @@
 ---
 title: Sifaka
+date-modified: 2026-02-09
 tags:
   - storage
 ---

docs/tutorials/adding-a-service.md

@@ -1,5 +1,6 @@
 ---
 title: Adding a Service
+date-modified: 2026-02-07
 tags:
   - tutorials
   - argocd

docs/tutorials/ai-assistance-guide.md

@@ -1,5 +1,6 @@
 ---
 title: AI Assistance Guide
+date-modified: 2026-02-09
 tags:
   - tutorials
   - ai

docs/tutorials/contributing.md

@@ -1,5 +1,6 @@
 ---
 title: Contributing
+date-modified: 2026-02-07
 tags:
   - tutorials
   - contributing

docs/tutorials/exploring-the-docs.md

@@ -1,5 +1,6 @@
 ---
 title: Exploring the Docs
+date-modified: 2026-02-10
 tags:
   - tutorials
   - getting-started

docs/tutorials/replicating-blumeops.md

@@ -1,5 +1,6 @@
 ---
 title: Replicating BlumeOps
+date-modified: 2026-02-07
 tags:
   - tutorials
   - replication

docs/tutorials/replication/argocd-config.md

@@ -1,5 +1,6 @@
 ---
 title: ArgoCD Config
+date-modified: 2026-02-07
 tags:
   - tutorials
   - replication

docs/tutorials/replication/core-services.md

@@ -1,5 +1,6 @@
 ---
 title: Core Services
+date-modified: 2026-02-07
 tags:
   - tutorials
   - replication

docs/tutorials/replication/kubernetes-bootstrap.md

@@ -1,5 +1,6 @@
 ---
 title: Kubernetes Bootstrap
+date-modified: 2026-02-07
 tags:
   - tutorials
   - replication

docs/tutorials/replication/observability-stack.md

@@ -1,5 +1,6 @@
 ---
 title: Observability Stack
+date-modified: 2026-02-07
 tags:
   - tutorials
   - replication

docs/tutorials/replication/tailscale-setup.md

@@ -1,5 +1,6 @@
 ---
 title: Tailscale Setup
+date-modified: 2026-02-07
 tags:
   - tutorials
   - replication

docs/tutorials/tutorials.md

@@ -1,5 +1,6 @@
 ---
 title: Tutorials
+date-modified: 2026-02-07
 tags:
   - tutorials
 ---

mise-tasks/docs-check-frontmatter

@@ -0,0 +1,86 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["rich>=13.0.0"]
+# ///
+#MISE description="Check that all docs have required frontmatter fields"
+"""Validate that all documentation files have required YAML frontmatter.
+
+Required fields: title, tags, date-modified
+
+Scans all markdown files in docs/ (excluding changelog.d/) and checks
+that each file has YAML frontmatter containing the required fields.
+
+Usage: mise run docs-check-frontmatter
+"""
+
+import re
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+DOCS_DIR = Path(__file__).parent.parent / "docs"
+REQUIRED_FIELDS = {"title", "tags", "date-modified"}
+
+# Match YAML frontmatter block
+FRONTMATTER_PATTERN = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+
+# Match top-level YAML keys (not indented)
+KEY_PATTERN = re.compile(r"^([a-zA-Z][a-zA-Z0-9_-]*):", re.MULTILINE)
+
+
+def extract_frontmatter_keys(file_path: Path) -> set[str] | None:
+    """Extract top-level keys from YAML frontmatter. Returns None if no frontmatter."""
+    content = file_path.read_text()
+    match = FRONTMATTER_PATTERN.match(content)
+    if not match:
+        return None
+    frontmatter = match.group(1)
+    return set(KEY_PATTERN.findall(frontmatter))
+
+
+def main() -> int:
+    console = Console()
+    console.print("[bold]Frontmatter Validation[/bold]")
+    console.print(f"Required fields: {', '.join(sorted(REQUIRED_FIELDS))}")
+    console.print()
+
+    issues: list[tuple[str, set[str]]] = []
+
+    for md_file in sorted(DOCS_DIR.rglob("*.md")):
+        if "changelog.d" in md_file.parts:
+            continue
+
+        rel_path = str(md_file.relative_to(DOCS_DIR))
+        keys = extract_frontmatter_keys(md_file)
+
+        if keys is None:
+            issues.append((rel_path, REQUIRED_FIELDS))
+            continue
+
+        missing = REQUIRED_FIELDS - keys
+        if missing:
+            issues.append((rel_path, missing))
+
+    if issues:
+        console.print("[bold red]Missing Required Frontmatter[/bold red]")
+        console.print()
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("File")
+        table.add_column("Missing Fields")
+
+        for rel_path, missing in issues:
+            table.add_row(rel_path, ", ".join(sorted(missing)))
+
+        console.print(table)
+        console.print()
+        return 1
+
+    console.print("[bold green]All docs have required frontmatter![/bold green]")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())