Erich Blume
b197bd5f58
## 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
86 lines
2.5 KiB
Text
Executable file
86 lines
2.5 KiB
Text
Executable file
#!/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())
|