aozgaa.github.io

Github Pages website.

Always a work-in-progress :).

Layout

• blog/*.adoc — post sources (AsciiDoc); blog/*.html — generated by make, committed
• blog/index.html — hand-maintained post table; blog/docinfo.html — shared <head> fragment
• everything else (index.html, links/, course_notes/, library/) — hand-written HTML, no build step

GitHub Pages serves these files as-is; no CI, no server-side build. Rebuild and commit the .html with every .adoc change or the published site goes stale.

Build and serve

make                 # build all posts
./scripts/serve.sh   # http://localhost:8080/ (PORT=9000 to override)
./scripts/watch.sh   # rebuild on save; Ctrl-C to stop
make clean           # delete generated blog/*.html

Typical loop: watch.sh in one terminal, serve.sh in another.

Hot reloading: rebuild only. watch.sh regenerates HTML on save (via entr, or inotifywait on Linux); nothing pushes to the browser, so reload the page yourself. make is incremental.

Dependencies

Gems are managed by bundler and pinned in Gemfile.lock, so every machine builds with identical versions. You supply the ruby; the repo supplies the rest.

bundle install      # installs into ./vendor/bundle (gitignored)

What your environment must provide:

• ruby >= 2.7 and bundler. p620 runs 3.2.3 (EOL 2026-04-01); this Mac runs MacPorts 4.0.7.
• a JavaScript runtime — asciidoctor-katex renders math through execjs. Node, or macOS’s built-in JavaScriptCore, will do; without one, only posts containing math fail.
• a UTF-8 locale (LANG=en_US.UTF-8 or similar). Under a US-ASCII locale execjs dies on posts with non-ASCII characters.
• optional: entr, or Linux inotify-tools — for watch.sh only

.bundle/config (committed) sets BUNDLE_PATH=vendor/bundle, so gems land in the repo rather than in a system gem dir you may not own. make invokes bundle exec asciidoctor.

Two notes on the pins, both learned the hard way:

• rouge must be 4+. rouge 3 ships different github theme CSS, which is inlined into every post with a source block, so building with it rewrites all of them. The lockfile makes this moot; the Gemfile constraint keeps it so.
• logger is declared explicitly. Ruby 4.0 moved it out of the default gems, but asciidoctor 2.0.26 still requires it without declaring the dependency, so bundle exec asciidoctor dies without it.

KaTeX math and rouge highlighting render at build time, so posts need no JavaScript to view. Only the KaTeX stylesheet comes from a CDN, via blog/docinfo.html.

Builds are reproducible (-a reproducible), so rebuilding a post with no source change produces no diff. Without it asciidoctor stamps the build time into every footer.

Pre-commit hooks

pre-commit install

• flowmark — formats .md at 120 columns
• build blog — runs make -B all. If that changes any generated HTML, pre-commit fails the commit with “files were modified by this hook”; the rebuilt files are already there, so git add blog/*.html and commit again. -B forces the rebuild because git does not preserve mtimes, which makes make’s staleness check unreliable here.

Adding a blog post

1. Create blog/<snake_case_name>.adoc:

   = Post Title
   :title: Post Title | Arthur Ozga
   :author: Arthur Ozga
   :revdate: yyyy-mm-dd
   :docinfo: shared

2. Add a row to blog/index.html (newest first, yyyymmdd).

3. make, check with ./scripts/serve.sh, commit the .adoc and the .html.

Markdown formatting

.md files are formatted by flowmark at 120 columns via a pre-commit hook. Install it with pre-commit install.