Revert the hidden section tabs, and revise all three docs #106
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Build and deploy Jekyll site to GitHub Pages | |
| on: | |
| push: | |
| branches: [ "main" ] | |
| # Runs the same four gates on the PR, so a change that breaks the build, the | |
| # plugin tests, an internal link, or the sitemap/metadata checks is caught | |
| # before it lands. Without this the gates only ran after a merge: a bad PR | |
| # reached main and merely failed to deploy, leaving main red. | |
| pull_request: | |
| branches: [ "main" ] | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| # No apt step. The packages it installed are already in the ubuntu-latest | |
| # image — a past run's log showed libyaml-dev/zlib1g-dev/libffi-dev | |
| # "already the newest version" and only 2 incidental upgrades — and the | |
| # -dev headers were only ever needed to compile Ruby itself, which | |
| # ruby/setup-ruby avoids by fetching a prebuilt build. The native gems | |
| # (sassc, eventmachine) need g++/make, which the image ships as well. | |
| # | |
| # What it did cost was `apt-get update` on every deploy: a network-bound | |
| # step that stalled for 45+ minutes twice in one day on a pipeline whose | |
| # other steps total under a minute. If this assumption is ever wrong the | |
| # build job fails and `deploy` (needs: build) publishes nothing. | |
| - name: Setup Ruby | |
| uses: ruby/setup-ruby@v1 | |
| with: | |
| # 3.3+: html-proofer's async→console dependency requires Ruby >= 3.3. | |
| ruby-version: '3.3' | |
| bundler-cache: true | |
| - name: Unit-test the Jekyll plugins | |
| # Plain `ruby`, not `bundle exec`: the plugins guard their Jekyll/Liquid | |
| # registrations behind `defined?`, so their logic loads standalone, and | |
| # minitest ships with Ruby. Runs before the build — these plugins decide | |
| # every page's description and read time. | |
| run: ruby test/run_all.rb | |
| - name: Setup Pages | |
| id: pages | |
| uses: actions/configure-pages@v5 | |
| - name: Build with Jekyll | |
| run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" --strict-front-matter | |
| env: | |
| JEKYLL_ENV: production | |
| - name: Validate HTML, internal links, and images | |
| # Catches broken internal links/anchors and missing images before deploy. | |
| # External links are skipped (slow, flaky); hash-only hrefs are allowed. | |
| # --swap-urls strips the Pages base_path so absolute /baseurl/... links | |
| # resolve against _site/ regardless of what base_path the build used. | |
| run: | | |
| bundle exec htmlproofer ./_site \ | |
| --disable-external \ | |
| --allow-hash-href \ | |
| --no-enforce-https \ | |
| --ignore-urls "/^\/page\/\d+/" \ | |
| --swap-urls "^${{ steps.pages.outputs.base_path }}:" | |
| - name: Validate discoverability (sitemap, feed, metadata) | |
| # Guards what htmlproofer does not look at: that the sitemap and feed | |
| # parse, that every page carries a description and a canonical, and that | |
| # no two pages share a description or title. Each check maps to a defect | |
| # this site actually shipped. | |
| run: script/validate-site.sh ./_site | |
| - name: Upload artifact | |
| # Nothing to publish from a PR run; the gates above are the whole point. | |
| if: github.event_name != 'pull_request' | |
| uses: actions/upload-pages-artifact@v3 | |
| deploy: | |
| if: github.event_name != 'pull_request' | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| needs: build | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |