Improve DX, add failing a11y tests (#142)

* Add a11y test (failing)

* Test on local build, document scripts, sort package.json

* Update dev guide

* Use local hugo to build site

* Fixup CI pipeline

* Document local vs global Hugo, role of Node

* Use hugo-bin instead of hugo-extended

* Update readme

* Revert "Update readme"

This reverts commit f368bcb.

* Revert "Use hugo-bin instead of hugo-extended"

This reverts commit 618d49d.

Author: mark-wiemer

.github/workflows/build.yml

@@ -5,22 +5,12 @@ on: [push, pull_request]
 jobs:
   build:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        hugo-version:
-          - 'latest'
-          - '0.134.2'
     steps:
       - uses: actions/checkout@v4
         with:
           submodules: true
           fetch-depth: 0
-
-      - name: Setup Hugo
-        uses: peaceiris/actions-hugo@v3
-        with:
-          hugo-version: ${{ matrix.hugo-version }}
-          extended: true
-
-      - name: Run Hugo
-        run: hugo --panicOnWarning
+      - name: Install depdencies
+        run: npm ci
+      - name: Build site to check for errors
+        run: npm run build:ci

.gitignore

@@ -13,4 +13,7 @@ hugo.linux
 /.hugo_build.lock
 
 # Node
-node_modules
+node_modules
+
+# A11y checker
+test-results

README.md

@@ -7,3 +7,24 @@ Theme: [hugo-book](https://themes.gohugo.io/themes/hugo-book/)
 See [/content](/content/) for content.
 
 See [About This Site](content/about-this-site/_index.md) for more information
+
+## package.json
+
+`package.json` dependencies and scripts are described here for readability:
+
+- scripts
+  - `build`: Builds the site to ensure changes are valid
+  - `build:ci`: Builds the site but fails if any warnings are detected. Used in our CI pipeline.
+  - `format:fix`: Fixes formatting of the `package.json` file
+  - `start`: Builds and serves the site at http://localhost:1313 with Hugo.
+  - `test:a11y`: Builds and serves the site, then uses Playwright and axe to test accessibility
+  - `test:a11y:tests`: Not meant for independent use, only as part of `test:a11y`
+  - `test:spelling`: Reports all apparent spelling errors. WIP, ref [#83](https://github.com/minetest/dev.luanti.org/issues/83) for details.
+- depdendencies
+  - `hugo-extended`: Static site generator that turns Markdown and shortcodes into HTML
+- devDependencies
+  - [`@axe-core/playwright`](https://npmjs.com/package/@axe-core/playwright): A11y tester bindings for Playwright
+  - [`@playwright/test`](https://npmjs.com/package/@playwright/test): Browser automation and test library
+  - [`cspell`](https://npmjs.com/package/cspell): Spellchecker
+  - [`sort-package-json`](https://npmjs.com/package/sort-package-json): Sorts package.json files for consistency
+  - [`start-server-and-test`](https://npmjs.com/package/start-server-and-test): Allows easy setup and teardown of complex tests, like our a11y tests

a11y/a11y.test.ts

@@ -0,0 +1,12 @@
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test.describe('homepage', () => {
+  test('should not have any automatically detectable accessibility issues', async ({ page }) => {
+    await page.goto('http://localhost:1313/');
+
+    const results = await new AxeBuilder({ page }).analyze();
+
+    expect(results.violations).toEqual([]);
+  });
+});

a11y/readme.md

@@ -0,0 +1,3 @@
+# Accessibility (a11y)
+
+This folder contains test files to help us review the accessibility of the site. We use `Playwright` and `axe` for this. Learn more at [Accessibility testing | Playwright](https://playwright.dev/docs/accessibility-testing).

content/about-this-site/local-development.md

@@ -6,9 +6,6 @@ title: Local Development
 
 _(anyone)_
 
-To build locally, you will need to first [install Hugo](https://gohugo.io/installation/).
-* Note, you need the extended version
-
 When cloning the repository you need to clone it recursively so that the theme submodule gets included:
 
 ```bash
@@ -22,17 +19,27 @@ git submodule init
 git submodule update --remote
 ```
 
-To launch the Hugo development server run `hugo server`. It will watch and regenerate whenever changes are made.
+This project uses [Hugo](https://gohugo.io/) to build the site and various Node packages to test it.
 
-To generate the site once without starting the server you can simply run `hugo`.
+You can install Hugo locally as a [Node.js](https://nodejs.org) package for convenience. Node is also used for further testing scripts, like spell-checking and a11y. These scripts are described in `package.json` and `readme.md`.
 
-Some additional checks are run in [Node](npmjs.org):
+To install and run via Node:
 
 ```bash
-npm install
-npm test
+npm install # Installs packages needed to build and test the site
+npm start # Builds and serves the site on a localhost port for manual testing
 ```
 
+If you prefer, you can manually install the relevant "extended" release globally from [Installation | Hugo](https://gohugo.io/installation/). Be sure to match the version present in `hugo.yaml`.
+
+To run globally:
+
+```bash
+hugo server # This is the command internal to the `npm start` command
+```
+
+## Spellchecker
+
 You can disable the spell checker with Hugo comments:
 
 ```md