The public console serves its guides at /docs. Readers do not need an operator
session or GitHub access. The existing Markdown files remain the content source;
the build publishes them into the self-contained Nitro output.
#Published content
The publisher includes docs/es and docs/en: their indexes, project overview,
translation policy, onboarding, architecture and decisions, providers, fidelity,
runtime, frontend and operations guides. History, agent instructions, contracts
and application source are excluded. References to excluded material remain text
with an explanatory tooltip, without an inaccessible link. Original files remain.
New guides in these sections are discovered automatically. Add a link to the
language's Markdown index to select its section and reading order. Optional
frontmatter supports title, description, navigation.title and
navigation.order. Titles otherwise come from H1; descriptions come from prose.
#Routes and links
docs/en/runtime/webhooks.md becomes /docs/en/runtime/webhooks. README and index
files map to their parent route, names are lowercase, and collisions fail the
build. /docs opens the Spanish index; each language has its own canonical URL.
The shared resolver transforms parsed Markdown links, including relative paths,
root documentation paths, query strings, anchors and known repository URLs.
External URLs and in-page anchors retain their meaning. The same route function
is used by links on the landing. Local images under docs are copied only when
referenced. Raw HTML and executable MDX components are disabled.
#Reading and search
The portal uses the existing public palette, typography and theme cookie, with PrimeVue dialogs and drawers. It includes collapsible navigation, breadcrumbs, heading anchors, an active H2/H3 table of contents, previous/next links and responsive tables. Code is highlighted at build time and has a copy button. Mermaid fences render as diagrams, with scrollable SVGs and expandable, copyable source. The renderer loads locally only on pages containing diagrams and follows the selected theme. Without JavaScript or if rendering fails, the source remains readable. Diagram links and raw HTML are disabled through Mermaid's strict mode.
Ctrl/Cmd+K opens local full-text search, including code and heading sections. The search index is loaded on demand for the current language; regular page requests load one page and navigation metadata. No external search service, Markdown parser or syntax highlighter runs in the browser.
#Validation and deployment
npm run docs:check
npm run test:docs
npm run typecheck --workspace @payment-emulator/console
npm run build --workspace @payment-emulator/console
Publication fails on missing guide links, missing heading anchors, missing images and route collisions. Diagnostics identify the source and target in the build log, never in the reader interface. Development watches the documentation tree; production requires a rebuild after content changes. Docker includes current guides in the build stage and ships only Nitro output in the runtime image.
Against a running console, npm run smoke:docs checks every published SSR route,
language, internal link and anchor, and the anonymous-access boundary. The optional
npm run smoke:docs:browser uses the same local Playwright/axe harness as the other
browser checks (BROWSER_TOOLS), and checks responsive layouts and interactions.
To prepare that optional harness after a fresh checkout:
npm install --prefix .tmp/landing-tools --no-save playwright @axe-core/playwright
npx --prefix .tmp/landing-tools playwright install chromium
npm run dev:console
In another terminal, run npm run smoke:docs and npm run smoke:docs:browser.
The default console origin is http://localhost:3000; set CONSOLE_URL for a
different address. Browser checks cover all published Mermaid diagrams in both
themes, source copying, language switching and mobile overflow. Screenshots and
the accessibility report are written to .tmp/shots/docs.