A minimal, pragmatic static blog setup intended to be generated by a Zig tool and deployed to GitHub Pages.
site.yml: site configuration (title, base URL, etc.)posts/: Markdown posts with YAML front matter (--- ... ---)static/: static assets copied into the outputdist/: generated site output (ignored by git; CI deploys this)
Edit site.yml to set site metadata (title, description, base_url) and directory names.
# Generate the site into dist/
zig build
# Serve dist/ locally (optional watch + rebuild on changes)
zig build serve- Create a new file under
posts/with YAML front matter:
---
title: My Post Title
date: "2025-12-14" # YYYY-MM-DD
slug: my-post # recommended (keeps the URL stable across renames)
description: Optional short summary
tags:
- zig
- meta
---Notes:
draft: truehides a post from generation.- Without
slug:, the generator uses the filename stem (posts/<stem>.md→/<stem>.html).
- Preview locally:
zig build
zig build serve- Publish via PR (auto-merge):
git checkout -b blog-my-post
git add posts/<file>.md static/<optional-assets>
git commit -m "Add post: <title> (blog-...)"
git push -u origin blog-my-post
# Open a PR and mark it for auto-merge after CI passes
gh pr create --fill --label auto-merge- Verify deploy + live site:
gh run list --workflow pages.yml --branch main --limit 1
gh run watch <run-id> --compact --exit-status --interval 10
curl -fsS -H "Cache-Control: no-cache" https://tkersey.github.io/ | rg -q "<Title>"
curl -fsS -H "Cache-Control: no-cache" https://tkersey.github.io/feed.xml | rg -q "<slug>"zig fmt --check build.zig src/*.zig
zig build test
# Autoformat
zig fmt build.zig src/*.zigThis repo deploys via .github/workflows/pages.yml using GitHub Actions.
Prereqs:
- The repo must support Pages (public, or a plan that supports private Pages).
- Settings → Pages → Build and deployment → Source = GitHub Actions.
Useful commands:
# Check Pages status (404 means not enabled yet)
gh api -i repos/tkersey/tkersey.github.io/pages
# Enable Pages with Actions as the build type
gh api -X POST repos/tkersey/tkersey.github.io/pages -f build_type=workflow
# Re-run the latest Deploy Pages workflow run (after enabling Pages)
gh run list --workflow pages.yml --limit 1
gh run rerun <run-id>This repo uses bd (beads). See AGENTS.md and .beads/BD_GUIDE.md.