Help center (Docusaurus)

The user-facing help center lives in docs/user/ and renders per-product guides plus the VPAT Parser API reference (Redocusaurus, from docs/api/vpat-parse-openapi.yaml).

Where it’s served

It has its own hostname:

https://help.theaccessible.org            → help center home
https://help.theaccessible.org/pdf/       → TheAccessiblePDF section
https://help.theaccessible.org/api/vpat-parse → API reference

docs/user/docusaurus.config.ts sets url: https://help.theaccessible.org and baseUrl: /. The site is served by a dedicated assets-only Cloudflare Worker defined in docs/user/wrangler.toml (Workers Static Assets over ./build) on the help.theaccessible.org custom domain.

Old location (redirected)

The help center used to be mounted at acr.theaccessible.org/docs, served by the apps/vpat worker. That worker now 301-redirects \/docs and \/docs/* to help.theaccessible.org, preserving the sub-path. The pre-reorg PDF guides are additionally covered by @docusaurus/plugin-client-redirects in the Docusaurus config — the three that moved under /pdf/ (e.g. /docs/convert-by-email → /pdf/convert-by-email) and the two retired ones (canvas-lti-setup, custom-gpt), which fall back to the /pdf/ hub rather than 404.

PDF app docs (pdf.theaccessible.org/docs). The converter’s own public help — 17 guides in apps/web/content/guides/*.md plus apps/web/content/faqs.md — was folded into this help center (Phase 2). The guides now live under /pdf/* (usage), /account-billing/* (account, billing, refunds), and /getting-started/getting-support; the FAQs became /pdf/faq; the four automation guides (MCP server, Claude Desktop skill, CI/CD, shared folder) were consolidated into /pdf/integrations. apps/web/public/_redirects 301s every old /docs/* URL to its new help-center home (per-slug rules first, a /docs/* catch-all to /pdf/getting-started/ last). /docs/internal stays served locally (admin-gated) via a passthrough rule placed before the catch-all. The Canvas LTI and ChatGPT Custom GPT guides were intentionally not migrated; their old URLs redirect to the /pdf/ hub. The apps/web/content/guides sources remain in the app repo (now shadowed by the redirects) and can be pruned in a follow-up.

Structure

Top-level sidebar sections are generated from the product registry (packages/accessible-org-ui/src/products.ts) so the help center can’t drift product-incomplete:

• docs/getting-started/ — landing + cross-product intro (first)
• docs/<product-id>/ — one section per registry product, in registry order
• docs/account-billing/ — sign-in, credits, plans, workshops (last)

scripts/sync-product-sections.mjs writes each section’s _category_.json (label = canonical product name, position = registry order). npm run build runs it first; npm run check:sections (CI) fails if a registry product has no docs section or the section metadata has drifted.

Build & deploy

cd docs/user
npm ci
npm run deploy        # sync:sections → docusaurus build → wrangler deploy

The docs build is validated in CI by .github/workflows/docs.yml on any PR touching docs/user/** or docs/api/** (build with onBrokenLinks: 'throw', the section-coverage check, and an accessibility scan of the built site).

Adding a new product’s help

1. Add the product to packages/accessible-org-ui/src/products.ts.
2. Create docs/user/docs/<id>/index.md (a short, accurate overview is enough).
3. npm run sync:sections to generate the section metadata.

Skipping step 2 makes check:sections fail in CI — by design.

To keep a registry product OUT of the help center (it stays in the footer / cross-promo but gets no help section), add its id to EXCLUDED_FROM_HELP in scripts/sync-product-sections.mjs and delete its docs/<id>/ directory. The check then stops requiring a section for it — and fails if a leftover one reappears.

Screenshots (visual walkthroughs)

PDF-section pages embed screenshots from docs/user/static/img/pdf/, referenced via <figure> + @theme/ThemedImage (light/dark pairs) or plain <img> (single variant). Images live in static/ so they publish at /img/pdf/<file>; alt text lives in the referencing .md.

These are copied from the PDF app’s curated set at apps/web/public/docs/screenshots/ (hand-captured — there is no automated generator yet). To refresh after a UI change: recapture in apps/web (light and dark for a themed pair), copy the file(s) into static/img/pdf/ keeping the same names, and confirm the alt text still matches. npm run build plus the pa11y CI gate (fails on a missing alt) catch broken or unlabeled images.

File(s)	Used on	Themed?
dashboard-empty.png (+ -dark)	pdf/getting-started (upload area)	yes
dashboard-row-expanded.png (+ -dark)	pdf/getting-started, pdf/downloading	yes
compare.png	pdf/downloading (Compare view)	no
documentsettings.jpg	pdf/downloading (Header & Footer)	no
documentstyling.jpg	pdf/downloading (Styling)	no

The sign-in screenshot was intentionally not used — the captured version showed retired “PDF Converter” branding and a stale “Send Magic Link” flow. Recapture on-brand (TheAccessiblePDF, one-time email code) before adding one. Other products (OrgChart, Audit) have no help-center screenshots yet.