2025 redesign

.github/workflows/build-jekyll.yml

@@ -0,0 +1,54 @@
+name: Build and Deploy
+on:
+  pull_request:
+    branches:
+      - gh-pages
+      - 2025-redesign
+  push:
+    branches:
+      - gh-pages
+      - 2025-redesign # TODO: Remove before merge
+  workflow_dispatch:
+
+# Prevent concurrent deploys
+concurrency:
+  group: "pages"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+      - name: Setup ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - name: Setup node
+        uses: bahmutov/npm-install@v1
+      - name: Setup pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build Jekyll
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" --profile
+        env:
+          JEKYLL_ENV: production
+          RUBYOPT: --yjit
+      - name: Upload
+        uses: actions/upload-pages-artifact@v4
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    # Only deploy on push, merge or manual
+    if: "github.event_name != 'pull_request'"
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/check-a11y-of-changed-content.yaml

@@ -36,7 +36,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 2.3
+          ruby-version: 3.4
 
       - name: Install gems
         run: bundle config path vendor/bundle && bundle install

.github/workflows/lint.yaml

@@ -2,8 +2,6 @@ name: Lint Posts
 
 on:
   pull_request:
-    branches:
-      - 'gh-pages'  # Runs when a PR targets the gh-pages branch
 
 jobs:
     lint-posts:

.pa11yci.js

@@ -1,33 +1,20 @@
 /// This is a configuration file automatically picked up by pa11y-ci.
 
-const relativeUrls = require('./pa11y-ci-urls');
+const relativeUrls = require("./pa11y-ci-urls");
 
-const chromiumBin = process.env.CHROMIUM_BIN;
-if (!chromiumBin) {
-  throw new Error('CHROMIUM_BIN environment variable is not set');
-}
-
-const baseUrl = 'http://localhost:4000';
+const baseUrl = "http://localhost:4000";
 
 // Colour contrast is a known issue. If we ever fix the brand colours, this should be removed.
 const colourContrastRuleIds = [
   // HTML CodeSniffer rule IDs come from section 1.4.3 of:
   // https://squizlabs.github.io/HTML_CodeSniffer/Standards/WCAG2/
-  'WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail', // normal text
-  'WCAG2AA.Principle1.Guideline1_4.1_4_3.G145.Fail', // large text
+  "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail", // normal text
+  "WCAG2AA.Principle1.Guideline1_4.1_4_3.G145.Fail", // large text
 ];
 
 module.exports = {
   defaults: {
-    chromeLaunchConfig: {
-      executablePath: chromiumBin,
-      "args": ["--no-sandbox"],
-    },
-    ignore: [
-      ...colourContrastRuleIds,
-    ],
-    reporter: 'cli',
-    runners: ['htmlcs'],
+    ignore: [...colourContrastRuleIds],
   },
   urls: relativeUrls.map((url) => `${baseUrl}${url}`),
 };

.prettierrc.json5

@@ -0,0 +1,11 @@
+{
+  plugins: ["@shopify/prettier-plugin-liquid"],
+  overrides: [
+    {
+      "files": "*.html",
+      "options": {
+        parser: "liquid-html"
+      }
+    }
+  ]
+}

Gemfile

@@ -1,12 +1,50 @@
 source 'http://rubygems.org'
-gem 'github-pages'
 
+gem "jekyll", "~> 4"
+group :jekyll_plugins do
+    # Deps from EOL github-pages gem minus themes
+    gem "jekyll-avatar"
+    gem "jekyll-commonmark"
+    gem "jekyll-default-layout"
+    gem "jekyll-feed"
+    gem "jekyll-gist"
+    gem "jekyll-github-metadata"
+    gem "jekyll-include-cache"
+    gem "jekyll-mentions"
+    gem "jekyll-optional-front-matter"
+    gem "jekyll-readme-index"
+    gem "jekyll-redirect-from"
+    gem "jekyll-relative-links"
+    gem "jekyll-remote-theme"
+    gem "jekyll-sass-converter"
+    gem "jekyll-seo-tag"
+    gem "jekyll-sitemap"
+    gem "jekyll-swiss"
+    gem "jekyll-titles-from-headings"
+    gem "jemoji"
+    gem "kramdown"
+    gem "kramdown-parser-gfm"
+    gem "liquid"
+    gem "mercenary"
+    gem "minima"
+    gem "nokogiri"
+    gem "rouge"
+    gem "terminal-table"
+    gem "webrick", "~> 1.7"
 
-gem "tzinfo-data", "~> 1.2022"
+    gem 'jekyll-paginate-v2'
 
-gem "webrick", "~> 1.7"
+    gem "tzinfo-data", "~> 1.2022"
 
-# Issue with ffi requiring a very recent rubygems version, not yet available
-# in many current linux docker images, so this must be locked down for now.
-# See https://github.com/ffi/ffi/issues/1103
-gem "ffi", "< 1.17.0"
+    gem "generate-json", "1.0.0", path: "gems/generate-json-gem"
+    gem "custom-filters", "1.0.0", path: "gems/custom-filters-gem"
+    gem "html-minify", "1.0.0", path: "gems/html-minify-gem"
+    gem "hook-exec", "1.0.0", path: "gems/hook-exec-gem"
+
+    gem "jekyll_plugin_support"
+
+    # Issue with ffi requiring a very recent rubygems version, not yet available
+    # in many current linux docker images, so this must be locked down for now.
+    # See https://github.com/ffi/ffi/issues/1103
+    gem "ffi", "< 1.17.0"
+end

README-DEV.md

@@ -0,0 +1,91 @@
+# Blog Development
+Useful things for working the blog itself (not blog posts).
+
+## Setup
+See [README.md](README.md).
+It has everything needed to get the blog up and running.
+
+## HTML
+Base layouts must be in `_layouts` and components must be in `_includes`.
+Within components, prefer passing variables in using `{%- include foo.html bar=baz -%}` rather than using the page
+context.
+This allows for includes to be cached using `{%- include_cached ... -%}` if they begin to consume too much build time.
+
+A few custom filters are provided by the `custom-filters` plugin:
+- `starts_with` - returns true if the given string starts with a given string
+  - `"https://example.com" | starts_with: "https"` resolves to `true`
+  - `"ftp://example.com" | starts_with: "https"` resolves to `false`
+  - `nil | starts_with: "https:"` resolves to `false`
+- `ends_with` - returns true if the given string ends with a given string
+  - `"foo.html" | ends_with: "html"` resolves to `true`
+  - `"foo.scss" | ends_with: "html"` resolves to `false`
+  - `nil | ends_with: "html"` resolves to `false`
+
+## Styles
+Blog stylesheets must be in `scss/`, be a partial stylesheet (be prefixed with an `_`) and `@use`'d by either 
+`assets/style.scss` or a stylesheet already `@use`'d by `assets/style.scss`.
+
+For example, the styles related to the author list are in `scss/_author-list.scss`, which is `@use`d by
+`assets/style.scss`, but `scss/_colours.scss` isn't `@use`'d by `assets/style.scss`.
+Rather `_colours` is `@use`d by other stylesheets such as `_author-list.scss`.
+
+Avoid deprecated SCSS features like `@import` where possible.
+If it cannot be avoided, include a comment with the reason why.
+For example `_util.scss` uses `@import` because the foundations framework still requires it.
+
+All stylesheets reachable from `assets/style.scss` are compiled and minified into `_site/assets/style.css` as part of
+the build process, using Jekyll's builtin SCSS support.
+
+## Scripts
+Blog scripts should be in `scripts/` and preferably be TypeScript (type safety is king).
+Where possible, try and import new scripts into `scripts/index.ts`.
+If this isn't possible, add the new script to `rspack.config.ts`'s `entry.page` array.
+
+The scripts are compiled, concatenated and minified using a custom build hook that triggers `rspack build`.
+
+## Build Hook
+To aid in development, arbitrary commands can be run at different Jekyll hooks by adding entries to `_config.yml`'s
+`hook_exec` entry.
+
+Each entry has the following structure:
+```yaml
+hook_exec:
+  owner:
+    event:
+      name:
+        cmd: string
+        env: optional map
+        priority: optional int
+```
+where:
+- `owner` and `event` are from the list in the [Jekyll docs](https://jekyllrb.com/docs/plugins/hooks/#built-in-hook-owners-and-events)
+with the `:` removed.
+- `name` is a useful identifier for logging
+- `cmd` is the command to run
+  - The value is treated as a [liquid template](https://shopify.github.io/liquid/)
+- `env` is a map of environment variables
+  - Values in the map are treated as [liquid template](https://shopify.github.io/liquid/)
+- `priority` is the priority of the hook with higher values being run first
+
+Liquid templates have access to the following variables, depending on which hook they are running in:
+- `site` - hooks with `:site` owner
+  - Same as the `site` object in normal templates
+- `doc` - hooks with `:document` owner
+  - [Jekyll document](https://github.com/jekyll/jekyll/blob/master/lib/jekyll/document.rb)
+- `page` - hooks with `:pages` owner
+  - Same as the `page` object in normal template
+- `payload` - hooks with either the `:pre_render` or `:post_render` event
+  - a hash containing variables to be used during rendering (`:pre_render`) or their final values after rendering 
+(`:post_render`)
+- `files` - hooks with `:clean` owner
+  - list of [files](https://ruby-doc.org/3.4.1/File.html) to be deleted
+
+For example, the `:site` `:pre_render` hook has the `site` and `payload` variables.
+
+These templates do not have access to [Jekyll specific filters and tags](https://jekyllrb.com/docs/liquid/).
+
+If a command produces a file in `_site`, it must be added to `_config.yml`'s `keep_file` list to prevent Jekyll from
+removing it as part of the build.
+
+This is primarily used to invoke external build commands.
+Anything more complicated should be implemented as a custom plugin, similar to the `html-minify` plugin.