Ground-up docs rewrite: Docura theme, full content restructure, search, and FAQ by nkbooth · Pull Request #89 · HamStudy/examtools-docs

nkbooth · 2026-05-01T14:47:22Z

Summary

This PR delivers a complete ground-up rewrite of the ExamTools end-user documentation, migrating from the legacy Wowchemy theme to a new Docura-based site with restructured content, a new information architecture, and significant content improvements.

Theme and infrastructure

Migrated from Wowchemy to Docura (selected after auditing multiple theme candidates)
Applied ExamTools brand colors site-wide (navy header, gold/blue accents)
ExamTools by SignalStuff logo in header; custom favicon; programmatic copyright year in footer
Customized landing page: dark navy hero, classExam2.svg background, three callout cards
Dark/night mode link color fixes; blockquote gold accent; sidebar section labels; article title weight
Fixed all Hugo deprecation warnings (languageCode→locale, languageName→label, .Site.Data→hugo.Data, .Language.LanguageName→.Language.Label)

Search

Implemented Pagefind static search (no external API dependency)
Magnifying-glass icon in header opens a modal search overlay

SEO and PWA

Open Graph and Twitter Card meta tags in head.html for social/Slack link previews
Upgraded OG image and PWA manifest icons to 512px ExamTools icon
Customized manifest.json with ExamTools name and theme color

Content — new and rewritten pages

All content written from scratch following the Diátaxis framework (quickstarts, how-tos, concepts, reference, troubleshooting):

account-setup: Create Account, Confirm VEC Accreditation, Add Signature
getting-started: New VE Quickstart, New Team Lead Quickstart
teams: Teams Overview, Create a Team, Become a Team Lead
sessions: Sessions Overview, Create a Session, Manage a Session
exam-day: Start a Session, Add an Applicant, Conduct an Exam, Complete an Applicant, Close a Session
paper-exams: Full workflow (8 pages)
applicants: Applicant-facing reference page (what to expect, PIN usage, exam interface)
remote-exams: Remote Exam Differences
reference: Environments, Glossary, Roles and Permissions
about: About ExamTools
troubleshooting: Account Issues, Session Issues, Get Help
faq.md: Expanded with 8 new entries covering team lead vs. owner/co-owner permissions, VEC credential sync timing, account requirements, the delegate step, session/applicant status differences, finalization prerequisites, "not part of session" warning, and accidental finalization

Content corrections

Aligned VEC sync timing language across add-vec-accreditation.md, become-team-lead.md, and faq.md: ExamTools reads VEC records every 4 hours; VECs update on their own schedule; allow up to 24–48 hours total

What's not in this PR

Screenshots (in progress — 52 markers identified across account-setup, getting-started, sessions, exam-day, paper-exams, teams)

Replace the legacy Wowchemy/Academic Hugo theme (last updated 2020) with the modern Hextra theme via git submodule. This rewrite consolidates the fragmented documentation structure into a clear, learner-centric hierarchy: getting-started, account-setup, teams, sessions, exam-day, paper-exams, remote-exams, about, applicants, reference, and troubleshooting. The old VEC-specific sections (arrl/, w5yi/, cve/, ve/) are consolidated into reusable how-to guides. Multi-file Hugo configuration (config/_default/) is replaced with a single, readable hugo.toml. Netlify build now uses Hugo 0.161.1 extended and properly initializes git submodules. This change positions the docs site for future maintainability, better mobile rendering, and faster iteration on content without template overhead. Breaking Change: Documentation URLs will change with the new theme structure. Refs: docs/rewrite-hextra

Complete rewrite of all end-user documentation using the Diátaxis framework (quickstarts, how-tos, reference, troubleshooting). New and restructured pages cover account setup, teams, sessions, exam day, paper exams, remote exams, and troubleshooting. Obsolete pages removed; new pages added (give-exam, complete-applicant, managing-applicants, add-ves-to-session, edit-team, manage-team-admins, callsign-change, faq). 52 screenshot markers placed throughout for future illustration. Replaces the Wowchemy-based site with Docura. Docura is customised via project-level layout overrides and examtools-custom.css — the theme itself is unmodified. Brand styling includes ExamTools navy header, gold/blue accent palette, ExamTools by SignalStuff logo, ExamTools favicon, and a dark hero landing page with classExam2.svg background and three quickstart callout cards.

- hugo.yaml: languageName→label, languageCode→locale - Project layout overrides: .Site.Data→hugo.Data (list, single, sidebar, article-footer), .Language.LanguageName→.Language.Label (site-header), .Site.LanguageCode→.Site.Language.Locale (baseof) - static/manifest.json: ExamTools name, navy theme color, brand icons

og:site_name, og:type (website/article), og:title, og:description, og:url, og:image; twitter:card summary with matching title/description/image. Image points to icon-180.png (best available — a dedicated 1200x630 OG image would improve previews).

Replace 180px placeholder with et_icon_512.png (navy rounded-square, gold antenna/A) in og:image, twitter:image, and manifest.json icons list.

- netlify.toml: chain 'npx pagefind --site public' after hugo in all three build contexts - head.html: load pagefind-ui.css/js and initialize PagefindUI on #site-header-search - .gitignore: exclude public/pagefind/ (generated artifact) - view.sh: prompt to build with Pagefind and serve statically, or fall back to hugo server - maintainer.md: document local search testing procedure

Three bugs fixed: 1. site-header.html was missing #site-header-search entirely — our earlier customization dropped the div, so no search container existed in the DOM. 2. Wrong Pagefind UI variant: the Default UI (pagefind-ui.js) renders an inline input field, unsuitable for a narrow header slot. The Component UI (pagefind-component-ui.js, introduced in Pagefind 1.5.0) renders a trigger button (search icon) that opens a full search modal — the correct pattern. 3. pagefind-modal must live in <body> separately from the trigger; added it to baseof.html just before the scripts partial. Result: search icon appears in the header; clicking it opens the Pagefind modal.

Covers finding a session, registration, PIN entry, exam interface navigation, and post-exam FCC application tracking. Primary message is to contact the VE team for anything session-specific. Wired into sidebar under "For Applicants" section.

New FAQ entries cover: team lead vs. owner/co-owner permissions, VEC credential sync timing, account requirement for paper-only VEs, delegate step explanation, session vs. applicant status, finalization prerequisites, 'You are not part of this session' alert, and recovering from accidental early finalization. Also corrects become-team-lead.md sync timing from 'a few hours' to the accurate 24-48 hour window with 4-hour polling cadence.

Update to match the accurate 24-48 hour / 4-hour polling language used in become-team-lead and the FAQ.

Pagefind uses optional chaining (?.) which requires Node 14+. Without an explicit NODE_VERSION, Netlify was defaulting to Node 12, causing the build to fail with "Unexpected token ?" when running npx pagefind.

Introduce sandbox environment documentation to guide VEs through practice workflows without affecting production records or VEC submissions. This includes a new "Sandbox and Training" section at weight 8, detailing how to create fake applicants, use dummy VEs (E/G prefix test accounts), interpret sandbox-specific visual indicators (sandcastle watermark, SandBox email prefix, beta CSCE URLs), and verify completed training sessions. Updates create-account.md with expanded sign-up form field details, a sandbox-specific callout with separate account and URL guidance, and a troubleshooting section addressing common verification and email issues. Links environments.md to the training-session guide. Adjusts nav weights (about +1, applicants +1, reference +1, troubleshooting +1) to accommodate sandbox at weight 8. The sandbox is now a first-class documented feature of the onboarding and training narrative, supporting both new VE ramp-up and ongoing practice for session managers.

nkbooth · 2026-05-01T20:27:07Z

Commits added since PR was opened

Three commits have landed on the branch after the PR was created:

`c2a1b7da` — fix: pin Node.js 20 in Netlify build environment

Adds NODE_VERSION = "20" to netlify.toml. Without this, Netlify was defaulting to Node 12, which does not support optional chaining (?.) — causing the Pagefind indexing step (npx pagefind) to fail with Unexpected token ? during the build.

Files changed: netlify.toml (+1 line)

`3555559a` — Screenshots and content tweaks across all major sections

⚠️ The commit message on this one is garbled (appears to be terminal output accidentally used as the message). The actual content is the screenshots work referenced in the PR description under "screenshots at all 52 markers."

Adds 43 new screenshot images across four sections (account-setup, paper-exams, sessions, teams) and makes corresponding prose tweaks to reference them — small wording adjustments, alt text hookups, and a few minor content corrections across 21 docs pages.

Files changed: 69 files — 21 .md files (content tweaks) + 48 .png images (new screenshots)

`b62569d0` — docs: add sandbox and training session documentation

Introduces the Sandbox and Training section as a first-class part of the docs:

New content/docs/sandbox/_index.md section landing page
New content/docs/sandbox/training-session.md how-to guide covering:
- Prerequisites (separate examtools.dev account; team lead permissions — auto-carried from production, or request manually from ExamTools support)
- Creating fake applicants (walk-in with FRN 0000000000 + "Create Fake", or register at hamstudy.dev)
- Using dummy VEs ([E|G][01-99]USR callsigns, passwordNN passwords, no stored signature — must draw manually)
- Taking a practice exam (= key shortcut to ace questions)
- Sandbox-specific visual differences: sandcastle watermark on PDFs, [SandBox/Dev]: email prefix, beta CSCE verification URL
Expanded create-account.md: sign-up form field details, sandbox callout (same process, substitute examtools.dev URLs), troubleshooting section (no confirmation email, 48h+ verification delay, rejected Official Copy, wrong callsign)
data/en/docs/sidebar.yaml: Sandbox and Training nav group added (Docura sidebar is manually defined here, not driven by content weights)
content/docs/reference/environments.md: link to training-session guide added
Weight bumps on about, applicants, reference, troubleshooting _index.md files (+1 each) to accommodate sandbox at weight 8

Files changed: 9 files — 2 new markdown pages, 5 updated _index.md weight fields, 1 sidebar YAML update, 1 environments reference update

… docs - Hero: halve classExam2.svg opacity (0.10 → 0.05) to reduce busyness - Hero cards: opaque dark-navy background + backdrop blur replaces near-transparent wash; text is now clearly readable against the SVG background - Doc watermark: reduce sandcastle-drawing.svg opacity to 0.018 and add saturate/contrast filter so it reads as texture rather than image - Light mode: off-white --background (#f6f8fa) reduces screen glare; article container gets a semi-transparent white lift (rgba 0.82) with subtle shadow, suppressed in dark/night modes

nkbooth added 11 commits April 30, 2026 21:12

Upgrade OG image and PWA manifest to 512px ExamTools icon

31e1297

Replace 180px placeholder with et_icon_512.png (navy rounded-square, gold antenna/A) in og:image, twitter:image, and manifest.json icons list.

Add applicant-facing reference page

d13b307

Covers finding a session, registration, PIN entry, exam interface navigation, and post-exam FCC application tracking. Primary message is to contact the VE team for anything session-specific. Wired into sidebar under "For Applicants" section.

Align VEC sync timing in add-vec-accreditation

3e0b717

Update to match the accurate 24-48 hour / 4-hour polling language used in become-team-lead and the FAQ.

fix: pin Node.js 20 in Netlify build environment

c2a1b7d

Pagefind uses optional chaining (?.) which requires Node 14+. Without an explicit NODE_VERSION, Netlify was defaulting to Node 12, causing the build to fail with "Unexpected token ?" when running npx pagefind.

nkbooth marked this pull request as ready for review May 1, 2026 15:11

nkbooth added 2 commits May 1, 2026 15:56

Usage: catter <file> [options...]

3555559

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Ground-up docs rewrite: Docura theme, full content restructure, search, and FAQ#89

Ground-up docs rewrite: Docura theme, full content restructure, search, and FAQ#89
nkbooth wants to merge 14 commits into
masterfrom
docs/rewrite-docura

nkbooth commented May 1, 2026 •

edited

Loading

Uh oh!

nkbooth commented May 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

nkbooth commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Theme and infrastructure

Search

SEO and PWA

Content — new and rewritten pages

Content corrections

What's not in this PR

Uh oh!

nkbooth commented May 1, 2026

Commits added since PR was opened

c2a1b7da — fix: pin Node.js 20 in Netlify build environment

3555559a — Screenshots and content tweaks across all major sections

b62569d0 — docs: add sandbox and training session documentation

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

nkbooth commented May 1, 2026 •

edited

Loading

`c2a1b7da` — fix: pin Node.js 20 in Netlify build environment

`3555559a` — Screenshots and content tweaks across all major sections

`b62569d0` — docs: add sandbox and training session documentation