From 8d01ba332c91c0e1e97c296c19ac38b0d532e2b6 Mon Sep 17 00:00:00 2001 From: Bill Stumbo Date: Thu, 12 Mar 2026 07:44:21 -0400 Subject: [PATCH 1/3] Update README.md - change Hugo version from latest to specific version Using latest was causing a build error because of breaking changes in the latest version of Hugo. The README file is now updated to use the same version of Hugo we are deploying to our website. Updated the GitHub action to check version of Hugo in README and deployed Hugo on push or pull. Fail operation if they have drifted apart. This will help ensure that when we roll the version of Hugo the documentation is correct. --- .github/workflows/gh-pages.yml | 42 +++++++++++++++++++++++++++++-- README.md | 46 ++++++++++++++++++---------------- 2 files changed, 65 insertions(+), 23 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 895e1075..b0426496 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -26,6 +26,10 @@ on: branches: - main # Set a branch to deploy + pull_request: + branches: + - main + schedule: - cron: "0 3 * * *" @@ -75,14 +79,47 @@ jobs: content/en/history/bibliography key: bib-${{ fromJson(steps.zoteroVersion.outputs.headers).last-modified-version }} + # ---------------------------------------------------------------------------- + # Validate that README.md references the correct Hugo version. + # Only runs on push/pull_request, not scheduled runs. + # + validate-docs: + if: github.event_name == 'push' || github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Check Hugo version consistency + run: | + echo "Checking README.md for Hugo version $HUGO_VERSION" + + # Check badge + if ! grep -q "badge/Hugo-${HUGO_VERSION}" README.md; then + echo "::error::README.md badge does not reference Hugo version $HUGO_VERSION" + FAILED=1 + fi + + # Check download URL + if ! grep -q "hugo_extended_${HUGO_VERSION}_linux-amd64.deb" README.md; then + echo "::error::README.md download URL does not reference Hugo version $HUGO_VERSION" + FAILED=1 + fi + + if [ "$FAILED" = "1" ]; then + echo "Update README.md to use Hugo version $HUGO_VERSION" + exit 1 + fi + + echo "README.md Hugo version references are consistent" + # ---------------------------------------------------------------------------- # Build the website. This job is conditional, we will always run it on a # push or if on a scheduled run the cache was determined to be out of date. # build: - needs: check + needs: [check, validate-docs] + if: always() && (github.event_name == 'push' || github.event_name == 'pull_request' || needs.check.outputs.cacheHit != 'true') && (needs.validate-docs.result == 'success' || needs.validate-docs.result == 'skipped') runs-on: ubuntu-latest - if: github.event_name == 'push' || needs.check.outputs.cacheHit != 'true' steps: - uses: actions/checkout@v4 with: @@ -140,6 +177,7 @@ jobs: path: ./public deploy: + if: github.event_name != 'pull_request' environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} diff --git a/README.md b/README.md index 25566713..e7af0625 100644 --- a/README.md +++ b/README.md @@ -163,22 +163,17 @@ Instructions for installing Hugo on various operating systems are at: [Installin For Ubuntu: ```bash -curl -s https://api.github.com/repos/gohugoio/hugo/releases/latest \ - | grep browser_download_url \ - | grep linux-amd64.deb \ - | grep extended \ - | cut -d '"' -f 4 \ - | wget -i - - -sudo dpkg -i hugo_extended*linux-amd64.deb +wget https://github.com/gohugoio/hugo/releases/download/v0.155.3/hugo_extended_0.155.3_linux-amd64.deb + +sudo dpkg -i hugo_extended_0.155.3_linux-amd64.deb ``` Verify installation: ```bash hugo version -# Expected output (version should be v0.145.0 or later): -hugo v0.155.2-d8c0dfccf72ab43db2b2bca1483a61c8660021d9+extended+withdeploy linux/amd64 BuildDate=2026-02-02T10:04:51Z VendorInfo=gohugoio +hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio + ``` ### Running the Development Server @@ -188,16 +183,16 @@ hugo v0.155.2-d8c0dfccf72ab43db2b2bca1483a61c8660021d9+extended+withdeploy linux 2. Start the Hugo development server: ```bash - hugo server --cleanDestinationDir --disableFastRender --renderToMemory +hugo server --cleanDestinationDir --disableFastRender --renderToMemory ``` Hugo will automatically download the Docsy theme and its dependencies as Hugo modules. Expected output: ```bash -Watching for changes in /home/wstumbo/development/Interlisp.github.io/archetypes, /home/wstumbo/development/Interlisp.github.io/assets/{css,icons,js,scss}, /home/wstumbo/development/Interlisp.github.io/content/en/{history,project,software}, /home/wstumbo/development/Interlisp.github.io/layouts/{_default,_partials,_shortcodes,bibliography,redirect}, /home/wstumbo/development/Interlisp.github.io/package.json, /home/wstumbo/development/Interlisp.github.io/static/{Resources,data,docs,documentation,favicons} -Watching for config changes in /home/wstumbo/development/Interlisp.github.io/config/_default, /home/wstumbo/development/Interlisp.github.io/config/development, /home/wstumbo/development/Interlisp.github.io/go.mod +Watching for changes in /archetypes, /assets/{css,icons,js,scss}, /content/en/{history,project,software}, /layouts/{_default,_partials,_shortcodes,bibliography,redirect}, /package.json, /static/{Resources,data,docs,documentation,favicons} +Watching for config changes in /config/_default, /config/development, /go.mod Start building sites … -hugo v0.155.2-d8c0dfccf72ab43db2b2bca1483a61c8660021d9+extended+withdeploy linux/amd64 BuildDate=2026-02-02T10:04:51Z VendorInfo=gohugoio +hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio WARN WARNING: 298 sidebar entries have been truncated. To avoid this, increase `params.ui.sidebar_menu_truncate` to at least 398 (from 100) in your config file. Section: /history/bibliography @@ -237,12 +232,13 @@ Building the website is driven by a GitHub workflow (`.github/workflows/gh-pages **Triggers:** - `push` to main — updates to the Interlisp.org website +- `pull_request` to main — validates changes before merge (builds but does not deploy) - Scheduled execution — ensures the bibliography remains consistent with Zotero - Manual execution — via the Actions panel in GitHub **Workflow Jobs:** -The workflow consists of three jobs: +The workflow consists of four jobs: **1. `check` — Verify Bibliography is Current** @@ -254,10 +250,18 @@ https://api.zotero.org/groups/2914042/items This returns metadata including the `Last-Modified-Version` header, which is incremented every time the Zotero Interlisp catalog is updated. This value is used as a cache key for the bibliography. If the cache key matches one in the current GitHub Action cache, we reuse the saved bibliography and skip rebuilding. -**2. `build` — Build the Website** +**2. `validate-docs` — Verify Documentation Consistency** + +Runs on `push` and `pull_request` events to ensure that README.md references the correct Hugo version. Checks that: +- The Hugo badge displays the version defined in `HUGO_VERSION` +- The README.md installation instructions use the correct version + +This job prevents documentation drift from the actual build configuration. + +**3. `build` — Build the Website** - Determines if a build is needed: - - On `push`: Always builds and deploys + - On `push` or `pull_request`: Always builds - On schedule: Skips build if Zotero cache is current - Checks out the repository - If the Zotero cache is valid, copies its contents into the `content/en/history/bibliography` directory @@ -267,9 +271,9 @@ This returns metadata including the `Last-Modified-Version` header, which is inc - `--cleanDestinationDir` — clears `./public` directory to avoid stale artifacts - Uses the GitHub `upload-pages-artifact` action to package and store the `./public` directory contents for deployment -**3. `deploy` — Deploy to GitHub Pages** +**4. `deploy` — Deploy to GitHub Pages** -Takes the output of the build step and deploys it to GitHub Pages using the GitHub `deploy-pages` action. +Takes the output of the build step and deploys it to GitHub Pages using the GitHub `deploy-pages` action. Skipped on pull requests. ### Environment Variables @@ -417,10 +421,10 @@ The site uses Google Custom Search to provide search results encompassing: - Interlisp GitHub repositories - Discussion groups for Medley and Interlisp -The search engine is configured in `config/params.yaml`: +The search engine is configured in `config/_default/params.yaml`: ```yaml -gcs_engine_id: 33ef4cbe0703b4f3ax +gcs_engine_id: 33ef4cbe0703b4f3a ``` Search results are rendered using the `search.html` layout template. From ddec26667a9e4e4e09b84057140324cbaac03818 Mon Sep 17 00:00:00 2001 From: Paolo Amoroso Date: Thu, 12 Mar 2026 16:53:51 +0100 Subject: [PATCH 2/3] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Paolo Amoroso --- .github/workflows/gh-pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index b0426496..618f3599 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -118,7 +118,7 @@ jobs: # build: needs: [check, validate-docs] - if: always() && (github.event_name == 'push' || github.event_name == 'pull_request' || needs.check.outputs.cacheHit != 'true') && (needs.validate-docs.result == 'success' || needs.validate-docs.result == 'skipped') + if: always() && (github.event_name == 'push' || github.event_name == 'pull_request' || needs.check.outputs.cacheHit != 'true') && (needs.validate-docs.result == 'success' || needs.validate-docs.result == 'skipped') && (needs.check.result == 'success' || needs.check.result == 'skipped') runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 From 14c59093aa75d61f924d12200ba6f5af44398d3f Mon Sep 17 00:00:00 2001 From: Paolo Amoroso Date: Thu, 12 Mar 2026 16:54:03 +0100 Subject: [PATCH 3/3] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Paolo Amoroso --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index e7af0625..ddb01006 100644 --- a/README.md +++ b/README.md @@ -172,6 +172,7 @@ Verify installation: ```bash hugo version +# Expected output: hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio ```