diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..8d21c99 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,67 @@ +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: + 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 + if: github.event_name != 'pull_request' + 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..3abb994 --- /dev/null +++ b/build.sh @@ -0,0 +1,18 @@ +#!/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 + +# 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 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