refactor(docs): switch to VitePress Plus theme with multi-version builds

[rh-hemartin]

Summary

Closes #5717

• Replace the default VitePress theme with @lando/vitepress-theme-default-plus, which provides built-in multi-version doc support via git-tag discovery and the mvb CLI
• Drop the hand-rolled escapeVueSyntax markdown preprocessor (the theme handles Vue syntax escaping)
• Add a versions landing page at docs/v/index.md and a sidebar version switcher
• Override the theme's pink/indigo accent palette with the project's green brand colors
• Simplify Vite alias resolution with import.meta.resolve instead of manual path.resolve chains

Test plan

• npm run docs:dev starts without errors and renders the site with green branding
• Version switcher appears in the sidebar with stable/edge/dev links
• npm run docs:build completes (mvb discovers tags and builds versioned output)
• Pages with {{ }} and non-HTML <tags> in markdown render correctly without the old preprocessor
• /v/ versions page lists discovered tags

🤖 Generated with Claude Code

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:59 PM UTC · Completed 2:19 PM UTC

Commit: 399214e · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

High

• [logic-error] docs/.vitepress/config.ts:68 — The Vite alias for vue changed from pointing to the package root (node_modules/vue, which has package.json with proper exports/module fields for Vite resolution) to path.dirname(resolve('vue')), which resolves to the dist/ subdirectory (e.g., node_modules/vue/dist/). This directory lacks a package.json, so Vite cannot resolve bare import 'vue' statements against it, potentially breaking the build.
  Remediation: Use resolve('vue') directly (the exact ESM entry file) instead of path.dirname(resolve('vue')), or use path.resolve(path.dirname(resolve('vue')), '..')to reach the package root.

• [scope-completeness] .github/workflows/site-build.yml — The CI workflow calls npm run docs:build, which this PR changes to invoke mvb docs. The mvb tool discovers documentation versions from git tags. If the CI checkout uses actions/checkout with the default shallow fetch (which excludes tags), mvb cannot discover versions and the multi-version build will be non-functional. Issue Add multi-version documentation support #5717 acceptance criterion Add problem areas: Tekton pipeline review, migration path, multi-tenancy #2 requires versioned builds from git tags.
  Remediation: Add fetch-depth: 0 or fetch-tags: true to the actions/checkout step in the site-build workflow so mvb can discover version tags.

• [scope-completeness] docs/doc-site.md — Issue Add multi-version documentation support #5717 acceptance criterion docs: add agent infrastructure problem document #5 requires documenting the versioning setup in docs/doc-site.md. The current file contains: (a) a stale reference to the vitepress build docs build command (now mvb docs), (b) no documentation of the VitePress Plus theme adoption or multiVersionBuild/sidebarEnder configuration, (c) a stale description of markdown processing that references the removed preConfig hook and escapeVueSyntax function, and (d) a "Documentation versioning (investigation)" section recommending against versioning — which contradicts this implementation.
  Remediation: Update docs/doc-site.md to document the VitePress Plus theme, multi-version build setup via mvb, and replace or update the obsolete versioning investigation section.

Medium

• [regression] docs/.vitepress/config.ts — The escapeVueSyntax preprocessor was removed, but the docs contain numerous bare angle-bracket patterns (e.g., <name>, <image>, <policy>) across markdown files that Vue will interpret as component tags. The ADR template backtick workaround in this same PR (see scope-alignment finding below) provides direct evidence that the Lando theme does not fully handle Vue syntax escaping, contradicting the PR description's claim.
  Remediation: Either retain the escapeVueSyntax preprocessor alongside the new theme, or systematically escape bare <placeholder> patterns across docs with backticks or :::v-pre containers.

• [layout-regression] docs/.vitepress/theme/index.ts:10 — Layout changed from slot-based composition ('layout-top' slot) to wrapping ReadingProgress and VPLTheme.Layout in a plain div. The extra wrapper div may break CSS assumptions (flex layouts, full-viewport positioning) that the VitePress theme relies on for root-level layout. The Lando theme extends VitePress and likely supports the same slot API.
  Remediation: Check if VPLTheme.Layout supports the 'layout-top' slot. If so, prefer h(VPLTheme.Layout, null, { 'layout-top': () => h(ReadingProgress) }).

• [scope-alignment] docs/ADRs/0000-adr-template.md:16 — The PR wraps {Accepted | Deprecated | Superseded} in backticks as a Vue escaping workaround, while simultaneously claiming the new theme handles Vue syntax escaping (justifying the escapeVueSyntax removal). If the theme handles escaping, this change is unnecessary; if it does not, the preprocessor removal will cause regressions across many docs. This internal inconsistency undermines the PR's core architectural claim.
  Remediation: Clarify whether the Lando theme handles Vue syntax escaping. Test the ADR template rendering with and without the backtick change.

Low

• [inconsistency] package.json:21 — docs:build uses mvb docs but docs:dev and docs:preview still use standard vitepress commands. This is likely fine since mvb is a production build concern, but should be verified.
  Remediation: Confirm npm run docs:dev starts without errors with the Lando theme's defineConfig.

---

Labels: PR modifies VitePress documentation infrastructure and adds multi-version doc support.

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

[fullsend-ai-review]

See the review comment for full details.

---

Note: The following inline comments could not be posted on the diff (GitHub returned 422) and are included here instead:

• docs/.vitepress/config.ts (file-level): Line 68 · [high] logic-error

The Vite alias for vue changed from pointing to the package root (which has package.json with proper exports/module fields) to path.dirname(resolve("vue")), which resolves to the dist/ subdirectory. This directory lacks a package.json, so Vite cannot resolve bare import "vue" statements against it, potentially breaking the build.

Suggested fix: Use resolve("vue") directly (the exact ESM entry file) instead of path.dirname(resolve("vue")), or use path.resolve(path.dirname(resolve("vue")), "..") to reach the package root.

• docs/.vitepress/theme/index.ts:10: [medium] layout-regression

Layout changed from slot-based composition (layout-top slot) to wrapping ReadingProgress and VPLTheme.Layout in a plain div. The extra wrapper div may break CSS assumptions (flex layouts, full-viewport positioning) that the VitePress theme relies on.

Suggested fix: Check if VPLTheme.Layout supports the layout-top slot. If so, prefer h(VPLTheme.Layout, null, { "layout-top": () => h(ReadingProgress) }).

• docs/ADRs/0000-adr-template.md:16: [medium] scope-alignment

The PR wraps {Accepted | Deprecated | Superseded} in backticks as a Vue escaping workaround, while simultaneously claiming the new theme handles Vue syntax escaping. This internal inconsistency undermines the core justification for removing escapeVueSyntax.

Suggested fix: Clarify whether the Lando theme handles Vue syntax escaping. Test ADR template rendering with and without the backtick change.

• package.json:21: [low] inconsistency

docs:build uses mvb docs but docs:dev and docs:preview still use standard vitepress commands. This is likely fine since mvb is a production build concern, but should be verified.

Suggested fix: Confirm npm run docs:dev starts without errors with the Lando theme defineConfig.