Adding a new guide

This is the internal playbook for turning a product guide (Word/PDF, e.g. Datamotive-User-Guide-2.0.3.docx) into docs pages. The golden rule: guides are source material, not page layouts. One guide becomes many task-focused pages slotted into the existing information architecture — never one giant page per guide.

Step 1 — Map guide sections to the IA

Read the guide's table of contents and map each section to an existing page slot in src/content/docs/_config.ts. Typical mappings:

If content has no natural slot, add a page: create the .mdx under the right section folder and register it in _config.ts (the slug must equal the file path without extension). The sidebar, search, prerender, and SEO all derive from that one config entry.

Step 2 — Convert, don't copy

• Restructure for the web. Guides narrate ("as shown in Figure 12"); docs pages instruct. Drop figure references, screenshot numbering, and repeated boilerplate.
• One task per page, with the wizard/CLI steps in a <Steps> block, parameters in <ParameterTable>, matrices in <SupportMatrixTable>, and warnings in <Callout type="warning">. The full component catalog is in the MDX authoring guide.
• Deduplicate across guides. When the User Guide and Deployment Guide describe the same feature, merge into the canonical page and link from the other context.
• Cross-link instead of repeating — port tables live once under core/networking/ports; everything else links there.
• Keep the product's exact vocabulary for UI labels, statuses (init-success, Pending CSP Validation), node names, and defaults.

Step 3 — Frontmatter and metadata

Every page needs frontmatter (see the authoring guide). For converted guides specifically:

• version — the solution version the guide documents (e.g. "2.0.3"), so staleness is traceable.
• last_updated — the conversion date; powers the "Recently updated" strip and staleness notices.
• tags/keywords — drive client-side search; include the terms an operator would actually type.

Step 4 — Register and badge

1. Add any new slugs to _config.ts in the right group, ordered to match the reading flow.
2. Badge new pages with badge: 'new' and substantially rewritten ones with badge: 'updated'; remove badges in the release after next.
3. If the guide introduces a new product area, add a section with accent, version, and changelogHref.

Step 5 — Verify

npm run typecheck   # _config.ts and component props
npm run build       # MDX compile + SSG prerender of every /docs slug

The build fails on malformed MDX, and the prerender step reports each docs page it writes — check the count went up by the number of pages you added. Then spot-check in npm run dev: sidebar placement, search hits for the new keywords, tables on mobile width, and dark mode.

Conversion record

Keep the provenance trail here so future updates know which guides are already integrated: