Static Site Generators in Production

Evaluating SSG Accessibility Defaults

Accessibility is usually treated as something a team adds after launch. In practice it is largely decided before launch, by the theme or starter the site is built on. The header markup, the sidebar's keyboard behaviour, the focus styles, the contrast of the code highlighting theme, the tab component for code samples — each is written once in a theme and repeated on every page. A good default gives a thousand accessible pages for free; a bad one produces a thousand issues that each cost a little to fix and are expensive to find.

This guide gives a two-hour evaluation procedure and applies it to the default themes of five options — Starlight, Docusaurus, VitePress, the Hugo Docsy theme and an Eleventy starter — on the same content. It adds the accessibility axis to the SSG Framework Selection Matrix.

Prerequisites

  • Each candidate built with a representative sample of real content: a long guide, a reference page with tables, a page with tabbed code samples, the homepage and the 404 page.
  • axe-core (via the browser extension, @axe-core/cli or Playwright), a keyboard and one screen reader (VoiceOver, NVDA or Orca).
  • About two hours per candidate.

Step 1: Automated Scan in Both Colour Schemes

Run axe-core against the five pages in light and dark mode. Dark themes are where contrast regressions hide, because they receive less testing.

// scripts/a11y-scan.mjs (Playwright + axe-core)
import { chromium } from 'playwright';
import AxeBuilder from '@axe-core/playwright';
const pages = ['/', '/guides/deploying/', '/reference/config/', '/guides/install/', '/nope/'];
const browser = await chromium.launch();
for (const scheme of ['light', 'dark']) {
  const ctx = await browser.newContext({ colorScheme: scheme });
  for (const p of pages) {
    const page = await ctx.newPage();
    await page.goto(`http://localhost:4321${p}`);
    const { violations } = await new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']).analyze();
    console.log(scheme, p, violations.map((v) => `${v.id}×${v.nodes.length}`).join(' '));
  }
}

Step 2: Keyboard and Structure Pass

Automated tools miss what matters most for keyboard users. With the mouse put away, check on each page:

  1. The first Tab reveals a skip link that moves focus to the main content.
  2. Focus is always visible, with a style that meets contrast against the background.
  3. Sidebar sections expand and collapse with Enter/Space; the current page is announced.
  4. Code tabs follow the ARIA tabs pattern: arrow keys move between tabs, Tab moves into the panel.
  5. Copy buttons are reachable, labelled, and announce success.
  6. Scrollable code blocks are focusable (so keyboard users can scroll them) but do not trap focus.
  7. The search dialog traps focus while open, closes with Escape and returns focus to its trigger.

Step 3: A Quick Screen-Reader Pass

On one long guide, navigate by headings and by landmarks. Check that there is exactly one h1, headings do not skip levels, landmarks (banner, navigation, main, contentinfo) exist and navigation landmarks have distinct labels ("Main", "Sidebar", "On this page"). Listen to a code block and a table: tables need header cells; code blocks should not be announced as a stream of separate spans.

The two-hour evaluation procedure Three stages across five sample pages. Automated axe-core scans in light and dark mode take about 20 minutes and catch contrast, alt text and ARIA errors. A keyboard pass of about 60 minutes checks skip link, focus visibility, sidebar, code tabs, copy buttons, scrollable regions and search dialog. A screen-reader pass of about 40 minutes checks headings, landmarks, tables and code blocks. Three passes, five pages, about two hours per candidate 1 · axe-core ~20 min · light + dark contrast alt text, link names ARIA misuse duplicate IDs 2 · keyboard ~60 min skip link, focus visible sidebar, code tabs copy buttons search dialog focus 3 · screen reader ~40 min · one long page one h1, heading order labelled landmarks table headers code block reading Automation finds the countable issues; people find the ones that block a task
The keyboard pass takes the longest and finds the issues that most often make a docs site unusable.

Results on Five Defaults

The five candidates with default themes and the same content. Automated counts are distinct axe rule violations across the ten page-and-scheme combinations; manual findings are failures of the seven keyboard checks and the structure checks.

Defaultaxe violations (light / dark)Keyboard checks failed (of 7)Structure issues
Starlight0 / 000
Docusaurus classic1 / 31 (code block scroll not focusable)0
VitePress default0 / 21 (code group tabs lack arrow keys)1 (sidebar nav unlabelled)
Hugo Docsy3 / 62 (no skip link; focus style low contrast)1 (heading skip in sidebar)
Eleventy starter (base blog)2 / n/a (no dark mode)1 (no skip link)0
Issues found in each default theme Stacked bars of total issues per default. Starlight 0. Docusaurus 5: 4 automated and 1 keyboard. VitePress 4: 2 automated, 1 keyboard and 1 structure. Hugo Docsy 12: 9 automated, 2 keyboard and 1 structure. Eleventy starter 3: 2 automated and 1 keyboard, with no dark mode to test. Issues per default theme, same content Starlight 0 Docusaurus 5 VitePress 4 Hugo Docsy 12 Eleventy starter 3 automated keyboard structure
Dark-mode contrast accounted for most automated findings; every theme that shipped a dark mode had more violations in it than in light mode, except Starlight.

Every issue found was fixable, most in under an hour; the Docsy findings took about a day in total because two sat in shared partials used across many templates. The point of the evaluation is not to disqualify candidates but to price the fixes into the decision, and to know which ones must land before launch.

The Defaults That Matter Most

Across the five, the same few defaults decided most of the outcome. Skip link — missing in two of five, trivial to add, essential for keyboard users on pages with long sidebars. Focus visibility — present everywhere, but low-contrast in one theme's dark mode. Code block handling — scrollable <pre> elements must be keyboard-focusable (tabindex="0" with a label) so content wider than the column can be read; this is also a WCAG requirement that axe reports as scrollable-region-focusable. Code tabs — implemented as buttons in some themes, which works, and as a full ARIA tabs pattern in others, which works better. Dark-mode contrast — syntax highlighting themes are the usual culprit; comments rendered in dim grey often fall below 4.5:1.

How many of the five defaults got each item right Bars out of five themes. Landmarks correct in 5. One h1 in 5. Visible focus in light mode in 5, but in dark mode only 4. Code tabs keyboard-operable in 4. Scrollable code blocks focusable in 3. Skip link present in 3. Dark-mode contrast clean in 2 of the 4 themes that had a dark mode. Defaults done right, out of five themes landmarks, one h1 5 focus visible (light) 5 code tabs keyboard-operable 4 scrollable code focusable 3 skip link 3 dark-mode contrast clean 2 of 4 The basics were universal; the differences were in dark mode, code blocks and skip links
Structural basics are solved everywhere; check the interactive and dark-mode details, which is where themes differ.

Beyond the Theme: Content Patterns

A clean theme can still host inaccessible content, and some content problems originate in how the generator encourages authoring. Three patterns showed up across the sample content. Images added through Markdown without alternative text — the fix is a build check that fails on ![](...) with empty alt, with an explicit alt="" convention for decorative images. Diagrams delivered as images of text, which screen readers cannot read — inline SVG with a <title> and <desc>, or a text description next to the image, fixes it. And link text such as "here" or "this page" repeated many times on a page, which is meaningless when a screen-reader user lists links — a Vale rule flags it in pull requests, as described in Editorial Checks with Vale in CI. Each is a content guideline plus an automated check, which is cheaper than finding the same problem on hundreds of pages later.

Keep It Tested

A default is only a starting point; content and customisations change it. Add the Step 1 scan to CI against the preview deploy, failing on any new violation, and repeat the manual passes when the theme changes. On the Starlight site chosen after this evaluation, the CI scan caught two regressions in its first quarter: an SVG diagram with low-contrast labels in dark mode, and a new callout component whose icon was announced as "image" with no label.

Pitfalls & Rollback

  • Testing the demo site. Evaluate with your own content; long tables and code samples expose issues demo pages do not.
  • Light mode only. Test both colour schemes; dark mode had more violations in four of five themes.
  • Treating a zero axe score as done. Keyboard and screen-reader checks find the issues that block tasks.
  • Fixing in content instead of templates. A missing table header fixed page by page will return; fix the component.
  • Ignoring reduced motion. Animated transitions and auto-playing demos should respect prefers-reduced-motion; check it with the OS setting enabled.
  • Rollback: the evaluation changes nothing; the fixes it prompts are ordinary template changes.

Conclusion

Accessibility on a static site is inherited from its theme far more than it is added later. A two-hour evaluation per candidate — automated scans in both colour schemes, a keyboard pass through navigation and interactive components, and a short screen-reader pass — showed default-theme issue counts from 0 to 12 on identical content. Price the fixes into the choice, land the essential ones before launch, and keep the automated scan in CI so the default you chose stays a good one.

FAQ

Is accessibility a property of the generator or of the theme?

Mostly the theme and the content. Generators decide little about markup, but docs frameworks ship full themes, and starter templates set patterns that teams copy for years. Evaluate the theme or starter you would actually use.

Can automated tools find all accessibility problems?

No. Tools such as axe-core find roughly a third to a half of issues, reliably catching contrast, missing alternative text, empty links and ARIA misuse. Keyboard navigation, focus order, reading order and meaningful link text need manual checks.

Which defaults matter most on documentation sites?

A skip link, one h1 and a logical heading order, landmarks for navigation and main content, visible focus styles, sufficient contrast in both light and dark themes, keyboard-accessible code tabs and copy buttons, and code blocks that do not trap focus.

How long does an evaluation take?

About two hours per candidate: automated scans of five representative pages in both colour schemes, a keyboard-only pass through navigation and interactive components, and a quick screen-reader pass on one page.