feat: upgrade docs to VitePress 2.0.0-alpha.17 with agent skills and UX improvements (#363)

- Upgrade VitePress from 1.6.4 to 2.0.0-alpha.17
- Add vitepress-plugin-group-icons for package manager and IDE icons in code tabs
- Add typedoc-plugin-frontmatter to suppress editLink/lastUpdated on generated API pages
- Add editLink ("Suggest changes to this page"), lastUpdated timestamps, and enhanced local search config
- Add "View as Markdown" / "Copy for LLM" buttons on all doc pages (aside on desktop, inline on mobile)
- Custom HomeLayout with hero → install sections → features → packages ordering
- New hero collage showing CLI, Agentforce Vibes, and Claude Code
- Rewrite homepage hero text and features to align with Salesforce platform strategy
- Rewrite agent-skills page: consolidated plugins table, Quick Start with marketplace install tabs for Agentforce Vibes, Claude Code, Copilot, Codex, and B2C CLI
- Rewrite introduction page with CLI-first, skills-second messaging
- Update SDK API docs: add operations/debug entry point, update package structure diagram, mark telemetry module as @internal
- Copy source .md files to build output via buildEnd hook for raw markdown access

Author: clavery

.changeset/vitepress-v2-upgrade.md

@@ -0,0 +1,9 @@
+---
+'@salesforce/b2c-dx-docs': patch
+---
+
+Upgrade documentation site to VitePress 2.0.0-alpha. Adds package-manager
+icons in `::: code-group` tabs (npm, pnpm, yarn, Homebrew), "Edit this page
+on GitHub" links, git-based "Last updated" timestamps, and improved local
+search ranking. Generated SDK API pages under `/api/` have edit and
+last-updated UI suppressed since they are regenerated on every build.

docs/.vitepress/config.mts

@@ -1,6 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import {defineConfig} from 'vitepress';
+import {groupIconMdPlugin, groupIconVitePlugin} from 'vitepress-plugin-group-icons';
 import typedocSidebar from '../api/typedoc-sidebar.json';
 
+// Copy source .md files to the build output so pages can be fetched as raw
+// markdown (powers the "View as Markdown" / "Copy for LLM" buttons).
+function copyMarkdownSources(srcDir: string, outDir: string) {
+  const entries = fs.readdirSync(srcDir, {withFileTypes: true});
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+    const src = path.join(srcDir, entry.name);
+    const dest = path.join(outDir, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(dest, {recursive: true});
+      copyMarkdownSources(src, dest);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      fs.copyFileSync(src, dest);
+    }
+  }
+}
+
 // Build configuration from environment
 const isDevBuild = process.env.IS_DEV_BUILD === 'true';
 
@@ -152,19 +172,64 @@ export default defineConfig({
 
   head: [['script', {}, versionSwitchScript]],
 
+  // Git-based "Last updated" timestamps (overridable per-page via frontmatter)
+  lastUpdated: true,
+
   // Ignore dead links in api-readme.md (links are valid after TypeDoc generates the API docs)
   ignoreDeadLinks: [/^\.\/clients\//],
 
-  // Show deeper heading levels in the outline
+  buildEnd(siteConfig) {
+    copyMarkdownSources(siteConfig.srcDir, siteConfig.outDir);
+  },
+
+  // Show deeper heading levels in the outline; register group-icons md plugin
   markdown: {
     toc: {level: [2, 3, 4]},
+    config(md) {
+      md.use(groupIconMdPlugin);
+    },
+  },
+
+  vite: {
+    plugins: [
+      groupIconVitePlugin({
+        customIcon: {
+          npx: 'vscode-icons:file-type-npm',
+          homebrew: 'logos:homebrew',
+          'agentforce vibes': {
+            light:
+              '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 36 56" fill="#333"><path d="M34 18h-7.9l6.8-15.2c0-.2.1-.5.1-.8 0-1.1-.9-2-2-2H9c-.9 0-1.7.6-1.9 1.5l-7 26c0 .2-.1.3-.1.5 0 1.1.9 2 2 2h7.5L4 53.5c0 .1-.1.3-.1.5 0 1.1.9 2 2 2 .6 0 1.2-.3 1.5-.7l28-34c.3-.4.5-.8.5-1.3.1-1.1-.8-2-1.9-2Z"/></svg>',
+            dark: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 36 56" fill="#e8e8e8"><path d="M34 18h-7.9l6.8-15.2c0-.2.1-.5.1-.8 0-1.1-.9-2-2-2H9c-.9 0-1.7.6-1.9 1.5l-7 26c0 .2-.1.3-.1.5 0 1.1.9 2 2 2h7.5L4 53.5c0 .1-.1.3-.1.5 0 1.1.9 2 2 2 .6 0 1.2-.3 1.5-.7l28-34c.3-.4.5-.8.5-1.3.1-1.1-.8-2-1.9-2Z"/></svg>',
+          },
+          'claude code': 'logos:claude-icon',
+          'copilot (vs code)': 'logos:visual-studio-code',
+          'copilot cli': {
+            light: 'logos:github-copilot',
+            dark: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#e8e8e8"><path d="M21.4 14.3A10 10 0 0 0 22 11C22 5.5 17.5 1 12 1S2 5.5 2 11c0 1.1.2 2.2.6 3.3A5 5 0 0 0 0 18.5C0 21 2 23 4.5 23H6a1 1 0 0 0 1-1v-4a1 1 0 0 0-1-1H5c-.3 0-.5-.2-.5-.5S4.7 16 5 16h1a3 3 0 0 1 3 3v3a1 1 0 0 0 1 1h4a1 1 0 0 0 1-1v-3a3 3 0 0 1 3-3h1c.3 0 .5.2.5.5s-.2.5-.5.5h-1a1 1 0 0 0-1 1v4a1 1 0 0 0 1 1h1.5c2.5 0 4.5-2 4.5-4.5a5 5 0 0 0-2.6-4.2zM8.5 12a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3zm7 0a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3z"/></svg>',
+          },
+          codex: {
+            light: 'simple-icons:openai',
+            dark: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#e8e8e8"><path d="M22.3 8.6a5.8 5.8 0 0 0-.5-4.8 5.9 5.9 0 0 0-6.4-2.8A5.8 5.8 0 0 0 11 0a5.9 5.9 0 0 0-5.6 4A5.8 5.8 0 0 0 1.5 6.6a5.9 5.9 0 0 0 .7 6.8 5.8 5.8 0 0 0 .5 4.8 5.9 5.9 0 0 0 6.4 2.8A5.8 5.8 0 0 0 13 22a5.9 5.9 0 0 0 5.6-4 5.8 5.8 0 0 0 3.9-2.6 5.9 5.9 0 0 0-.7-6.8zM13 20.6a4.4 4.4 0 0 1-2.8-1l.2-.1 4.6-2.6a.7.7 0 0 0 .4-.7V10l2 1.1v5.7a4.4 4.4 0 0 1-4.4 3.8zm-9.4-3.5c-.6-1-.8-2.1-.5-3.2l.2.1 4.6 2.6a.7.7 0 0 0 .8 0l5.6-3.2v2.3l-4.7 2.7a4.4 4.4 0 0 1-6-1.3zM2.3 7.9A4.4 4.4 0 0 1 4.6 6v.2l.1 5.3a.7.7 0 0 0 .3.6l5.6 3.2-2 1.1L4 13.8A4.4 4.4 0 0 1 2.3 8zM18 10l-5.6-3.2 2-1.2 4.6 2.7a4.4 4.4 0 0 1-.7 7.9v-5.5a.7.7 0 0 0-.3-.6zm2-3.2-.2-.1-4.6-2.7a.7.7 0 0 0-.8 0L8.8 7.3V5l4.7-2.7a4.4 4.4 0 0 1 6.5 4.6zm-12 4L6 9.7V4a4.4 4.4 0 0 1 7.2-3.4l-.2.1L8.4 3.3a.7.7 0 0 0-.4.7zm1-2.2 2.5-1.4 2.5 1.4v2.9L9.5 13l-2.5-1.5z"/></svg>',
+          },
+          'b2c cli': 'logos:salesforce',
+        },
+      }),
+    ],
   },
 
   themeConfig: {
     logo: '/logo.svg',
     outline: {
       level: [2, 3],
     },
+    editLink: {
+      pattern: 'https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/edit/main/docs/:path',
+      text: 'Suggest changes to this page',
+    },
+    lastUpdated: {
+      text: 'Last updated',
+      formatOptions: {dateStyle: 'medium'},
+    },
     nav: [
       {text: 'Guides', link: '/guide/'},
       {text: 'MCP', link: '/mcp/'},
@@ -199,6 +264,16 @@ export default defineConfig({
 
     search: {
       provider: 'local',
+      options: {
+        detailedView: true,
+        miniSearch: {
+          searchOptions: {
+            fuzzy: 0.2,
+            prefix: true,
+            boost: {title: 4, text: 2, titles: 1},
+          },
+        },
+      },
     },
   },
 });

docs/.vitepress/theme/HomeLayout.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import VPHomeHero from 'vitepress/dist/client/theme-default/components/VPHomeHero.vue';
+import VPHomeFeatures from 'vitepress/dist/client/theme-default/components/VPHomeFeatures.vue';
+import VPHomeContent from 'vitepress/dist/client/theme-default/components/VPHomeContent.vue';
+import {useData} from 'vitepress';
+import HomePackages from './HomePackages.vue';
+
+const {frontmatter, theme} = useData();
+</script>
+
+<template>
+  <div
+    class="VPHome"
+    :class="{'external-link-icon-enabled': theme.externalLinkIcon}"
+  >
+    <VPHomeHero />
+
+    <VPHomeContent v-if="frontmatter.markdownStyles !== false" class="home-install-section">
+      <Content />
+    </VPHomeContent>
+    <Content v-else />
+
+    <VPHomeFeatures />
+
+    <HomePackages />
+  </div>
+</template>
+
+<style scoped>
+.VPHome {
+  margin-bottom: 96px;
+}
+
+@media (min-width: 768px) {
+  .VPHome {
+    margin-bottom: 128px;
+  }
+}
+
+.home-install-section {
+  margin-top: 24px;
+  margin-bottom: 48px;
+}
+
+@media (min-width: 768px) {
+  .home-install-section {
+    margin-top: 32px;
+    margin-bottom: 64px;
+  }
+}
+
+.home-install-section :deep(h2) {
+  border-top: none;
+  padding-top: 0;
+  margin-top: 0;
+}
+
+</style>

docs/.vitepress/theme/HomePackages.vue

@@ -0,0 +1,50 @@
+<template>
+  <section class="home-packages">
+    <div class="container vp-doc">
+      <h2 id="packages">Packages</h2>
+      <table>
+        <thead>
+          <tr><th>Package</th><th>Description</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><a href="https://www.npmjs.com/package/@salesforce/b2c-cli"><code>@salesforce/b2c-cli</code></a></td>
+            <td>Command-line tools for Salesforce B2C Commerce</td>
+          </tr>
+          <tr>
+            <td><a href="https://www.npmjs.com/package/@salesforce/b2c-dx-mcp"><code>@salesforce/b2c-dx-mcp</code></a></td>
+            <td>MCP Server for AI-assisted development</td>
+          </tr>
+          <tr>
+            <td><a href="https://www.npmjs.com/package/@salesforce/b2c-tooling-sdk"><code>@salesforce/b2c-tooling-sdk</code></a></td>
+            <td>SDK library for custom integrations</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.home-packages {
+  padding: 0 24px;
+  margin-top: 64px;
+}
+
+@media (min-width: 640px) {
+  .home-packages {
+    padding: 0 48px;
+  }
+}
+
+@media (min-width: 960px) {
+  .home-packages {
+    padding: 0 64px;
+  }
+}
+
+.container {
+  margin: 0 auto;
+  max-width: 1152px;
+}
+</style>