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#89nkbooth wants to merge 19 commits into
Conversation
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.
Commits added since PR was openedThree commits have landed on the branch after the PR was created:
|
… 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
|
I give training to VEs on how to use exam.tools, I always start in the sandbox and never in production so combining the create account for both sandbox and production I'm not a fan of. I want to be able to point the trainee to the create sandbox account like I do now with the current documentation. I don't want to have to have a conversation with the candidate to give them enough context to follow what is in this update |
I'm not sure I fully understand the problem; can you elaborate? As far as creating an account I would generally think it would be much easier to create both accounts at the same time and submit verification for each. |
|
Just to confirm I'm understanding, you're advocating for 2 different pages, one for the sandbox and one for the production site, that are exactly the same but with the URLs swapped? I think there's probably ways to solve your concern of "new VEs don't understand the difference between the 2 sites and i need to get them into training before explaining it" without duplication of pages and maintenance burden. Would calling out sandbox vs. live in line with first class links to both help better? Or maybe a more clear callout sentence or two at the head of the document? |
I usually have someone that is very experienced with the old ARRL way of giving exams, or someone that has never given an exam. I find giving explicit guidance on the process to follow to get setup for the training really helps both cases. I have had folks get a production account and expect that to work for training so I try and steer them away from getting a production account until the training is complete. The training I do is online and all the things a VE does in the session is actually done. I don't want to point a person at the documentation that will confuse them more about what they need to do. People have a hard time following directions ;-) |
Perhaps a parameter on the URL could be used to customize the page contents between production and sandbox? It that parameter doesn't exist then showing it the combined way would be ok. One think I think about is "can the person really answer the question I'm asking" in my training cases they can't answer whats on the create account page very well so I have to do more work with them before the session. |
I may not have been entirely clear here; I mean 2 distinct pages (new prod account, new sandbox account), with the walkthrough URLs matching the title destination.
The docs for both environments are combined; they have no concept of "sandbox docs" vs. "Production docs" - both programatically and in prose. The code and docs aren't intended to diverge; they're intended to be mirrors with a small handful of exceptions so that they're effectively mirrors. Then the sandbox is a testing ground that is isolated from production, but still behaviorally authoritative. Docs should theoretically not need additional mirrors in a perfect world.
This is what i think would be most value add knowing - what are the parts of the docs around setting up an account that experienced VEs aren't understanding or getting friction from? That's what I'd like to solve. |
The web says that query parameters can be used in the doc to customize output so I don't understand the "both programitically" statement. The confusion arises with examtools having 2 identity systems one for sandbox and one for production. Newbies can't figure that out easily. I do personally like the seperate identities because it allows me to be a laurel team lead in the sandbox when I am not one in production, this is because I help out with CVE training for various VECs. I'm just trying to make my life as a trainer easier. I will figure out how to make things work out in any case. I hope that comes across. Thanks, |
3 participants
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
classExam2.svgbackground, three callout cardslanguageCode→locale,languageName→label,.Site.Data→hugo.Data,.Language.LanguageName→.Language.Label)Search
SEO and PWA
head.htmlfor social/Slack link previewsmanifest.jsonwith ExamTools name and theme colorContent — new and rewritten pages
All content written from scratch following the Diátaxis framework (quickstarts, how-tos, concepts, reference, troubleshooting):
Content corrections
add-vec-accreditation.md,become-team-lead.md, andfaq.md: ExamTools reads VEC records every 4 hours; VECs update on their own schedule; allow up to 24–48 hours totalWhat's not in this PR