From 33aa2f1efe64e7271d0b78952a1209368cf0b66d Mon Sep 17 00:00:00 2001 From: zyansheep Date: Mon, 27 Jul 2026 14:02:04 -0700 Subject: [PATCH 1/3] Build and deploy via GitHub Actions The site was built locally and its output committed to a second repo (libdither/dither.link-build) mounted as the `public` submodule. That arrangement dates to 2022-04-18, when a CI workflow was tried and dropped the same day: it ran non-extended Hugo (the book theme needs extended for SCSS), never ran mdbook so /docs/ was missing, and actions/deploy-pages did not exist yet. None of those blockers still apply. Pushes to main now build and deploy straight to Pages: - add .github/workflows/deploy.yml, pinning hugo-extended 0.115.0, mdbook 0.4.31 and mdbook-katex 0.5.4 to match the nix devshell. Checkout is recursive because /docs/ comes from dither-spec and static/disp/interactive-walkthrough.html is a symlink into disp. - add build.sh, shared by the devshell and CI. It clears public/ first, which drops stale fingerprinted assets that had accumulated since Hugo never removes old output. - drop the public submodule and gitignore the directory; stop tracking .hugo_build.lock. - remove build-push.sh, and fix the flake buildPhase, which invoked `hugoix` and so had never worked. Verified: build.sh output is byte-identical to the last published build, minus two orphaned search-index files from an older run. Co-Authored-By: Claude --- .github/workflows/deploy.yml | 64 ++++++++++++++++++++++++++++++++++++ .gitignore | 5 +-- .gitmodules | 3 -- .hugo_build.lock | 0 README.md | 32 ++++++++++++++++++ build-push.sh | 13 -------- build.sh | 12 +++++++ flake.nix | 2 +- public | 1 - 9 files changed, 112 insertions(+), 20 deletions(-) create mode 100644 .github/workflows/deploy.yml delete mode 100644 .hugo_build.lock delete mode 100644 build-push.sh create mode 100755 build.sh delete mode 160000 public diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..e75cd81 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,64 @@ +name: Build and deploy site + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +# Queue deploys rather than cancelling them, so a push mid-deploy can't leave +# the live site half-updated. +concurrency: + group: pages + cancel-in-progress: false + +env: + # Pinned to match the nix devshell, so CI output is byte-identical to a + # local build. Bump these together with flake.lock. + HUGO_VERSION: 0.115.0 + MDBOOK_VERSION: 0.4.31 + MDBOOK_KATEX_VERSION: 0.5.4 + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + # Recursive is required: /docs/ is built from the dither-spec + # submodule, and static/disp/interactive-walkthrough.html is a + # symlink into the disp submodule that Hugo follows. + submodules: recursive + + - name: Install toolchain + run: | + set -euo pipefail + mkdir -p "$RUNNER_TEMP/bin" + curl -sSfL "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" \ + | tar -xz -C "$RUNNER_TEMP/bin" hugo + curl -sSfL "https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz" \ + | tar -xz -C "$RUNNER_TEMP/bin" mdbook + curl -sSfL "https://github.com/lzanini/mdbook-katex/releases/download/v${MDBOOK_KATEX_VERSION}/mdbook-katex-v${MDBOOK_KATEX_VERSION}-x86_64-unknown-linux-gnu.tar.gz" \ + | tar -xz -C "$RUNNER_TEMP/bin" mdbook-katex + echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH" + + - name: Build + run: ./build.sh + + - uses: actions/upload-pages-artifact@v3 + with: + path: ./public + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index e50adfd..a4a9483 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ result resources -# public -.direnv \ No newline at end of file +public +.direnv +.hugo_build.lock diff --git a/.gitmodules b/.gitmodules index 043549a..5f6a2ff 100644 --- a/.gitmodules +++ b/.gitmodules @@ -4,9 +4,6 @@ [submodule "themes/book"] path = themes/book url = https://github.com/alex-shpak/hugo-book -[submodule "public"] - path = public - url = https://github.com/libdither/dither.link-build.git [submodule "disp"] path = disp url = https://github.com/libdither/disp diff --git a/.hugo_build.lock b/.hugo_build.lock deleted file mode 100644 index e69de29..0000000 diff --git a/README.md b/README.md index 1ff9f5b..75b92c8 100644 --- a/README.md +++ b/README.md @@ -3,3 +3,35 @@ Website for Dither, hosts the entirety of [libdither/dither-spec](https://github.com/libdither/dither-spec) in addition to an introduction to Dither More to be added in the future (such as a blog and perhaps a simple commenting system). + +## Publishing + +Pushing to `main` builds and deploys the site to via +GitHub Actions (`.github/workflows/deploy.yml`). There is nothing to run by +hand — `public/` is build output and is no longer committed. + +To publish a change to the spec: + +```sh +cd dither-spec +# edit, then +git commit -am "..." && git push +cd .. +git commit -am "dither-spec: ..." dither-spec # bump the submodule pointer +git push # triggers the deploy +``` + +## Local development + +Requires [nix](https://nixos.org) with flakes (or hugo-extended, mdbook and +mdbook-katex on `PATH`). `direnv allow` picks up the devshell automatically. + +```sh +nix develop # hugo-extended, mdbook, mdbook-katex +hugo server # live preview of the site shell +./build.sh # full build (site + /docs/) into public/ +``` + +CI pins the same tool versions the devshell provides, so a local `./build.sh` +produces byte-identical output to a deploy. When bumping `flake.lock`, update +the pinned versions in `.github/workflows/deploy.yml` to match. diff --git a/build-push.sh b/build-push.sh deleted file mode 100644 index 92b9c78..0000000 --- a/build-push.sh +++ /dev/null @@ -1,13 +0,0 @@ -#!/usr/bin/env bash -mdbook build dither-spec -d ../public/docs -hugo -pushd public -git add . -git commit -m "build" -git push -popd -# Only commit & push build directory -git restore --staged . -git add public -git commit -m "update build" -git push \ No newline at end of file diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..32ab534 --- /dev/null +++ b/build.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +# Build the full site into public/. Used by both `nix develop` locally and CI. +set -euo pipefail +cd "$(dirname "$0")" + +# Hugo never removes stale output, so old fingerprinted assets accumulate +# across builds. Start clean instead. +rm -rf public + +# Hugo first: it owns the site root. mdbook then fills in /docs/ underneath. +hugo --gc +mdbook build dither-spec -d ../public/docs diff --git a/flake.nix b/flake.nix index 563bf6a..2d3b509 100644 --- a/flake.nix +++ b/flake.nix @@ -26,7 +26,7 @@ src = ./.; nativeBuildInputs = buildInputs; buildPhase = '' - hugoix + ./build.sh ''; installPhase = '' cp -r public $out diff --git a/public b/public deleted file mode 160000 index b61841d..0000000 --- a/public +++ /dev/null @@ -1 +0,0 @@ -Subproject commit b61841d4524e04b8ef6f81f5fd512f0d625bd5a6 From 63555a10a28fd5b7b36944f80eca96cded6b3af7 Mon Sep 17 00:00:00 2001 From: zyansheep Date: Mon, 27 Jul 2026 14:02:38 -0700 Subject: [PATCH 2/3] Build on PRs too, deploy only from main Co-Authored-By: Claude --- .github/workflows/deploy.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index e75cd81..8d21c99 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -3,6 +3,8 @@ name: Build and deploy site on: push: branches: [main] + # Build (but don't deploy) on PRs, so a broken build is caught before merge. + pull_request: workflow_dispatch: permissions: @@ -55,6 +57,7 @@ jobs: deploy: needs: build + if: github.event_name != 'pull_request' runs-on: ubuntu-latest environment: name: github-pages From e3125528d9ac702b5b8c61ddff58bcf0e9a10630 Mon Sep 17 00:00:00 2001 From: zyansheep Date: Mon, 27 Jul 2026 14:04:31 -0700 Subject: [PATCH 3/3] Drop mdbook's copy of dither-spec git metadata and stale build dir book.toml sets src = ".", so mdbook copies every non-markdown file in the submodule into /docs/. Locally that pulled in .git and a nested public/docs tree left by running mdbook there without -d -- the latter is on the live site today. A fresh CI checkout has neither, so removing them makes a local build byte-identical to the CI artifact (190 files). Co-Authored-By: Claude --- build.sh | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/build.sh b/build.sh index 32ab534..3abb994 100755 --- a/build.sh +++ b/build.sh @@ -10,3 +10,9 @@ rm -rf public # Hugo first: it owns the site root. mdbook then fills in /docs/ underneath. hugo --gc mdbook build dither-spec -d ../public/docs + +# dither-spec/book.toml sets src = ".", so mdbook copies every non-markdown +# file in the submodule into the output -- including its git metadata and any +# stale build dir left behind by running `mdbook build` there without -d. A +# fresh CI checkout has neither; drop them so local builds match. +rm -rf public/docs/.git public/docs/public