docs: interactive Quickstart guides#454
Open
clavery wants to merge 5 commits into
Open
Conversation
Adds /quickstart/ — an interactive setup wizard that walks users through the minimum config for a specific task (deploy, jobs, sandbox, MCP setup, etc.) and synthesises a dw.json snippet, anchored checklist, and verify command. - Slot-based <Wizard> / <QStep> / <QChoice> Vue SFCs (provide/inject) - One adventure per .vue file under docs/.vitepress/adventures/, page shims under docs/quickstart/, metadata stubs under data/adventures/ - Index page with priority sections, search, and tag-pill filtering - Build-time anchor checker validates every doc link across all reachable choice combinations - Auto-injected Copy buttons on inline code blocks via useCopyableCode Adventures: deploy-code, agent-mcp, sandbox, vscode-extension (core); jobs, page-designer, ci-cd, scapi-access, logs, debug, account-manager, cartridge-path, multi-instance (common); mrt-deploy, slas-clients, migrate-sfcc-ci (specialized); script-api-docs (niche).
Moves all 17 adventures from per-page .vue components back to typed Adventure objects under data/adventures/. The QuickstartAdventure orchestrator (with ?qs= preset support) is now the single renderer; the declarative <Wizard>/<QStep>/<QChoice> components are removed. Why: split source of truth made anchor validation a false positive — the build-time checker was iterating empty metadata stubs. Presets weren't wired up on slot-based pages either. With one Adventure object per adventure, the index, presets, validation, and renderer all consume the same typed data. What changed: - defineAdventure / step / choice / md / doc helpers in _authoring.ts - Choice gains a body field rendered as markdown via the new _markdown.ts helper (links resolve through withBase; supports inline code, bold, italic, lists, fenced code) - AdventureOutput renderWarning now uses the same markdown renderer, so links/bold/inline code in warnings render correctly instead of as raw Markdown text - MarkdownActions skips /quickstart/<id>.md shims (Copy-for-LLM was empty there) - Anchor checker walks real synthesizer output across reachable choice combinations — false positives caught (e.g., wrong sfcc-ci-migration slug), now corrected
…bytes - Add Choice.body field that the renderer already reads (was missing from the type, so adventure files using `body: md\`...\`` only type-checked by accident). - Type ocapiConfig() against an explicit OcapiResource shape so the readonly-tuple-with-spread error stops being a tsc warning. - Replace fragile space-padded placeholders in the markdown renderer with explicit __B2CMD_PLACEHOLDER_<n>__ sentinels, so user content with " digit " can't collide with the inline-code stash. - Hide MarkdownActions on every /quickstart/ page (sub-pages and the index) — both raw .md sources are 3-line component shims with no useful content for Copy-for-LLM. - Anchor checker now also walks markdown links inside Choice.body and synthesizer warning strings, not just Step.docAnchor + checklist. Same logic added to the standalone scripts/check-adventure-anchors.ts. - New docs:typecheck script (tsc --noEmit) so the docs workspace is actually type-checked. Adds a Vue file shim and a doc-scoped tsconfig. Repo's typecheck:agent doesn't cover docs, so this catches what reviewer-found regressions like the missing Choice.body that used to slip through.
Keeps "Adventure" / "defineAdventure" as internal terminology and surfaces Quickstart guides in the contributor docs so they get maintained alongside the rest of the documentation. Renames (visible to doc authors editing .md): - Component: <QuickstartAdventure adventure-id="X"> → <QuickstartGuide id="X"> - File: theme/adventure/QuickstartAdventure.vue → QuickstartGuide.vue - Build messages: "Setup Adventure anchor check…" → "Quickstart anchor…" The Adventure type, defineAdventure helper, and the data files under docs/.vitepress/data/adventures/ keep their names — the user's instruction was that "adventure" stays internal-to-code, and these are code. Skill / context updates: - AGENTS.md (root): adds a Quickstart-guide bullet under Documentation, pointing at the data dir, build-time anchor checker, and the evaluate-impact contract. - .claude/skills/documentation/SKILL.md: new "Quickstart Guides" section describing structure, helpers, when-to-update / when-to-add / when-to- remove rules. Updated the maintenance checklist (CLI command added, CLI behavior changed, configuration option added, doc heading renamed) with explicit Quickstart sweeps. Extended the "When Adding Configuration Options" path to call out _helpers.ts placeholders + SCOPE_BUNDLES. - .claude/skills/cli-command-development/SKILL.md: adds step 11 to the Creating-a-Command Checklist — evaluate Quickstart-guide impact, run the anchor checker.
clavery
requested review from
patricksullivansf,
wei-liu-sf and
yhsieh1
as code owners
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds 17 interactive Quickstart guides at
/quickstart/that walk users through the minimum config for a specific task and synthesise a copy-paste-readydw.json(or.env), an anchored checklist that links back into the prose docs, and a single command that proves the setup works.The guides are authored as typed
Adventureobjects underdocs/.vitepress/data/adventures/using a small helper layer (defineAdventure/step/choice/md/doc). Each one renders through a single<QuickstartGuide id="…" />component on its page shim. The data is the single source of truth for the index card grid, the preset deep-links, the build-time anchor checker, and the wizard renderer.Coverage:
Index page features:
Wizard features:
showIfconditional steps that hide based on prior picksdw.json/.envtabs, fenced JSON warnings (e.g., OCAPI snippet), numbered checklist with anchor links, single verify command?qs=<preset-id>deep-link supportBuild-time validation:
pnpm --filter @salesforce/b2c-dx-docs run docs:typecheck— strict tsc over the docs workspace, catches Choice / Adventure type drift.(state, choice)combination per guide and validates everystep.docAnchor, every checklistlink()href, every internal[text](/path#anchor)inside choicebodymarkdown, and every link inside synthesizerwarnings. Failed slugs fail the build with a precise message.Contributor docs:
AGENTS.md: new bullet under Documentation pointing at the guides, the build-time anchor checker, and the maintenance contract..claude/skills/documentation/SKILL.md: new "Quickstart Guides" section with file layout, authoring template, helper reference table, when-to-update / when-to-add / when-to-remove rules. Existing maintenance checklists (CLI command added, CLI behavior changed, configuration option added, doc heading renamed) gained explicit Quickstart sweeps..claude/skills/cli-command-development/SKILL.md: step 11 of the Creating-a-Command Checklist now prompts evaluating Quickstart impact + running the anchor checker.PLAN_guides.md(root): tracks the prioritised backlog of additional guides not yet built.Internal terminology: the implementation uses the legacy term
Adventure/defineAdventureinside.tsfiles; user-visible UI strings, page shims, and contributor docs say "Quickstart guide". The component prop isid, notadventure-id.Test plan
pnpm --filter @salesforce/b2c-dx-docs run docs:typecheckpassespnpm --filter @salesforce/b2c-dx-docs run docs:buildpasses with✓ All Quickstart anchors resolve (17 guides checked)pnpm run typecheck:agentpasses (no regressions in repo-wide typecheck)pnpm run lint:agentpasses (no new lint errors; pre-existingb2c-dx-mcperrors unrelated)/quickstart/) renders 17 guides across 4 priority sections with tag filter and search/quickstart/jobs) — each step's choices, multi-select where applicable, synthesized output renders dw.json + warning JSON + checklist + verify command, anchor links resolve, copy buttons work/quickstart/agent-mcp?qs=claude-code-skills-mcplands on a fully-filled wizard with synthesized outputMarkdownActions(Copy-for-LLM / View-as-Markdown) hidden on/quickstart/pages but still present on/guide/and/cli//quickstart/;Setupnav entry now readsQuickstartOut of scope (tracked in
PLAN_guides.md)