Add dedicated QA script for website testing

.github/workflows/build.yml

@@ -42,10 +42,16 @@ jobs:
 
       - name: Install Dependencies
         run: npm ci
+
+      - name: Install Playwright Browsers
+        run: npx playwright install --with-deps
 
       - name: Run Linting
         run: npm run lint
-
+
+      - name: Run Markdown Linting
+        run: npm run lint:markdown
+
       - name: Run Spell Check (Source)
         run: npm run spellcheck
 

.gitignore

@@ -26,4 +26,9 @@ pnpm-debug.log*
 
 # CSpell cache
 .cspellcache
-/test-results
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

.markdownlint.yaml

@@ -0,0 +1,56 @@
+# markdownlint configuration
+# See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+# Heading hierarchy rules
+MD001: true  # heading-increment - headings should only increment by one level at a time
+MD025: true  # single-title/single-h1 - documents should have a single top-level heading
+
+# Heading style rules
+MD003:       # heading-style - heading style should be consistent
+  style: atx # Use ATX style (##) not Setext style (underlines)
+MD018: true  # no-missing-space-atx - no space after hash on atx style heading
+MD019: true  # no-multiple-space-atx - multiple spaces after hash on atx style heading
+MD023: true  # heading-start-left - headings must start at the beginning of the line
+MD024:       # no-duplicate-heading - multiple headings with the same content
+  siblings_only: true # Allow duplicate headings in different sections
+MD026:       # no-trailing-punctuation - trailing punctuation in heading
+  punctuation: ".,;:!" # Don't allow these, but allow ? for questions
+
+# First line rules
+MD041: false # first-line-heading/first-line-h1 - disabled because we use frontmatter
+
+# Line length
+MD013: false # line-length - disabled for prose content
+
+# Code blocks
+MD046:       # code-block-style - code block style should be consistent
+  style: fenced # Use fenced code blocks (```) not indented
+
+# Lists
+MD004:       # ul-style - unordered list style should be consistent
+  style: dash # Use dashes for unordered lists
+MD029:       # ol-prefix - ordered list item prefix
+  style: ordered # Use sequential numbers (1, 2, 3) not all 1s
+MD030:       # list-marker-space - spaces after list markers
+  ul_single: 1
+  ul_multi: 1
+  ol_single: 1
+  ol_multi: 1
+
+# Blank lines
+MD012:       # no-multiple-blanks - multiple consecutive blank lines
+  maximum: 2 # Allow up to 2 blank lines for visual separation
+MD022:       # blanks-around-headings - headings should be surrounded by blank lines
+  lines_above: 1
+  lines_below: 1
+
+# Inline HTML
+MD033: false # no-inline-html - disabled to allow inline HTML in MDX
+
+# Emphasis
+MD036: false # no-emphasis-as-heading - disabled to allow emphasized text that looks like headings
+
+# Whitespace and formatting
+MD009: false # no-trailing-spaces - disabled as trailing spaces don't affect rendering
+MD007: false # ul-indent - disabled to allow flexible list indentation
+MD060: false # table-column-style - disabled as table alignment is cosmetic

AGENTS.md

@@ -0,0 +1,99 @@
+# Guide to `plx.github.io`
+
+This file provides guidance to coding agents like Claude Code and Codex.
+
+## Repository Overview
+
+This is an Astro-based static site deployed to GitHub Pages. The site uses Tailwind CSS for styling and is built using npm/Node.js, then deployed via GitHub Actions; as such, any changes pushed to `main` will be automatically deployed—convenient, but be careful!
+
+## Key Commands
+
+The repository includes a justfile to gather all project commands in a single place; if you're unsure "how do I X?", look there first.
+
+It also manages the preview server using a tool called `trop` (https://github.com/plx/trop).
+
+Some key commands are:
+
+- just install: installs dependencies (npm ci)
+- just preview: launches dev server with hot reload (port automatically allocated by trop)
+- just shutdown: kills dev server if running (port automatically allocated by trop)
+- just build: builds the site for production (to dist/)
+- just spellcheck: checks spelling in source files
+- just spellcheck-html: checks spelling in built HTML output
+- just lint: runs ESLint on all files
+- just lint-fix: auto-fixes ESLint issues where possible
+- just validate: runs all validation checks (lint + spellcheck + build + links)
+
+## Key Technical Decisions
+
+- **Framework**: Astro with React integration
+- **Styling**: Tailwind CSS with Typography plugin
+- **Content**: MDX support for enhanced markdown
+- **Build**: Static site generation to `dist/` folder
+- **Deployment**: GitHub Actions workflow deploys to GitHub Pages
+- **Site URL**: https://plx.github.io
+
+Additionally, we aim to have *reasonable* accessibility support throughout the site.
+
+## Content Structure
+
+The site's content is organized into three main collections:
+
+- Blog posts (longer-form articles): `src/content/blog/`
+- Briefs (short notes): `src/content/briefs/`
+- Projects: `src/content/projects/`
+
+Here are brief remarks about each.
+
+### Blog Posts
+
+Structured as folders containing *at least* an `index.md` file, placed in `src/content/blog/`; for example, `my-new-post` looks like:
+
+```
+src/content/blog/my-new-post/
+src/content/blog/my-new-post/index.md
+```
+
+Posts should include front matter with relevant metadata.
+
+### Briefs (Short Notes)
+
+Organized into categories represented as folders within `src/content/briefs/`, and stored *directly* as markdown files (no additional nesting / generic `index.md`).
+For example, the following contains two briefs—one in the `swift-warts` category and one in the `claude-code` category:
+
+```
+src/content/briefs/swift-warts/my-swift-brief.md
+src/content/briefs/claude-code/my-claude-brief.md
+```
+
+Categories are auto-discovered from folder names. To add a new category, simply create a new folder.
+Categories may also customize their display name, description, and sort priority by establishing a `category.yaml` file in the category folder; this is useful because the category name is used in multiple places throughout the site, and benefits from having distinct, contextually-appropriate representations.
+
+### Projects (Descriptions of Projects)
+
+Structured analogously to "Blog Posts`, but placed in `src/content/projects/`, instead.
+
+## Directory Structure
+
+- `src/`: Source code
+  - `components/`: Astro components
+  - `content/`: Content collections (blog, briefs, projects)
+    - `blog/`: where blog posts live
+    - `briefs/`: where briefs live
+    - `projects/`: where project pages live
+  - `layouts/`: Page layouts
+  - `pages/`: Routes and pages
+  - `styles/`: Global styles
+  - `lib/`: Utilities
+- `public/`: Static assets (fonts, images, etc.)
+- `dist/`: Build output (generated, not in repo)
+- `.github/workflows/`: GitHub Actions workflows
+
+## Testing and QA
+
+The repository has Playwright browser automation available via MCP for testing and QA purposes. This enables:
+
+- Visual testing and screenshot capture
+- Navigation testing
+- Content verification
+- Browser automation tasks

CLAUDE.md

@@ -1,98 +1 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Repository Overview
-
-This is an Astro-based static site deployed to GitHub Pages. The site uses Tailwind CSS for styling and is built using npm/Node.js, then deployed via GitHub Actions; as such, any changes pushed to `main` will be automatically deployed—convenient, but be careful!
-
-## Key Commands
-
-The repository includes a justfile to gather all project commands in a single place; if you're unsure "how do I X?", look there first.
-It also manages the preview server using a tool called `trop` (https://github.com/plx/trop).
-
-Some key commands are:
-
-- just install: installs dependencies (npm ci)
-- just preview: launches dev server with hot reload (port automatically allocated by trop)
-- just shutdown: kills dev server if running (port automatically allocated by trop)
-- just build: builds the site for production (to dist/)
-- just spellcheck: checks spelling in source files
-- just spellcheck-html: checks spelling in built HTML output
-- just lint: runs ESLint on all files
-- just lint-fix: auto-fixes ESLint issues where possible
-- just validate: runs all validation checks (lint + spellcheck + build + links)
-
-## Key Technical Decisions
-
-- **Framework**: Astro with React integration
-- **Styling**: Tailwind CSS with Typography plugin
-- **Content**: MDX support for enhanced markdown
-- **Build**: Static site generation to `dist/` folder
-- **Deployment**: GitHub Actions workflow deploys to GitHub Pages
-- **Site URL**: https://plx.github.io
-
-Additionally, we aim to have *reasonable* accessibility support throughout the site.
-
-## Content Structure
-
-The site's content is organized into three main collections:
-
-- Blog posts (longer-form articles): `src/content/blog/`
-- Briefs (short notes): `src/content/briefs/`
-- Projects: `src/content/projects/`
-
-Here are brief remarks about each.
-
-### Blog Posts
-
-Structured as folders containing *at least* an `index.md` file, placed in `src/content/blog/`; for example, `my-new-post` looks like:
-
-```
-src/content/blog/my-new-post/
-src/content/blog/my-new-post/index.md
-```
-
-Posts should include front matter with relevant metadata.
-
-### Briefs (Short Notes)
-
-Organized into categories represented as folders within `src/content/briefs/`, and stored *directly* as markdown files (no additional nesting / generic `index.md`).
-For example, the following contains two briefs—one in the `swift-warts` category and one in the `claude-code` category:
-
-```
-src/content/briefs/swift-warts/my-swift-brief.md
-src/content/briefs/claude-code/my-claude-brief.md
-```
-
-Categories are auto-discovered from folder names. To add a new category, simply create a new folder.
-Categories may also customize their display name, description, and sort priority by establishing a `category.yaml` file in the category folder; this is useful because the category name is used in multiple places throughout the site, and benefits from having distinct, contextually-appropriate representations.
-
-### Projects (Descriptions of Projects)
-
-Structured analogously to "Blog Posts`, but placed in `src/content/projects/`, instead.
-
-## Directory Structure
-
-- `src/`: Source code
-  - `components/`: Astro components
-  - `content/`: Content collections (blog, briefs, projects)
-    - `blog/`: where blog posts live
-    - `briefs/`: where briefs live
-    - `projects/`: where project pages live
-  - `layouts/`: Page layouts
-  - `pages/`: Routes and pages
-  - `styles/`: Global styles
-  - `lib/`: Utilities
-- `public/`: Static assets (fonts, images, etc.)
-- `dist/`: Build output (generated, not in repo)
-- `.github/workflows/`: GitHub Actions workflows
-
-## Testing and QA
-
-The repository has Playwright browser automation available via MCP for testing and QA purposes. This enables:
-
-- Visual testing and screenshot capture
-- Navigation testing
-- Content verification
-- Browser automation tasks
+@AGENTS.md

justfile

@@ -33,6 +33,11 @@ clean:
 install:
     npm install
 
+# Setup: full project setup including dependencies and Playwright browsers
+setup:
+    npm install
+    npx playwright install
+
 # Spellcheck: checks spelling in source files
 spellcheck:
     npm run spellcheck
@@ -53,10 +58,54 @@ lint:
 lint-fix:
     npm run lint:fix
 
+# Lint-markdown: runs markdownlint on content files
+lint-markdown:
+    npm run lint:markdown
+
 # Validate: runs all validation checks (lint + spellcheck + build + links)
 validate:
     npm run validate:all
 
+# QA: runs all Playwright QA tests (full suite for CI)
+qa:
+    npm run qa
+
+# QA-quick: runs quick sample of tests for local development
+qa-quick:
+    npm run qa:quick
+
+# QA-full: runs complete test suite including all sitemap pages
+qa-full:
+    npm run qa:full
+
+# QA-comprehensive: runs only the comprehensive sitemap tests
+qa-comprehensive:
+    npm run qa:comprehensive
+
+# QA-core: runs only the core tests (not comprehensive)
+qa-core:
+    npm run qa:core
+
+# QA-headed: runs Playwright tests with visible browser
+qa-headed:
+    npm run qa:headed
+
+# QA-ui: opens Playwright UI for interactive testing
+qa-ui:
+    npm run qa:ui
+
+# QA-debug: runs Playwright tests in debug mode
+qa-debug:
+    npm run qa:debug
+
+# QA-report: shows Playwright test report
+qa-report:
+    npm run qa:report
+
+# QA-codegen: opens Playwright code generator
+qa-codegen:
+    npm run qa:codegen
+
 # Learn-spelling: adds new words to cspell dictionary (comma-separated)
 learn-spelling words:
-    node scripts/learn-spelling.js {{words}}
+    node scripts/learn-spelling.js {{words}}