docs: migrate to shared @fhir-toolkit/docs-theme (#3)

* chore(deps): migrate pnpm config from package.json to pnpm-workspace.yaml; bump packageManager to pnpm 11

- Remove `pnpm.onlyBuiltDependencies` from package.json (removed in pnpm 11)
- Create pnpm-workspace.yaml with allowBuilds map (esbuild, lefthook)
- Bump packageManager to pnpm@11.1.3
- Bump engines.pnpm to >=11.0.0

Removes the pnpm 10 pin that was a tactical measure during the Node 22
engine bump. Reference: https://pnpm.io/migration

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: scaffold Astro + Starlight, replace VitePress

Replace docs/site/.vitepress/ with Astro 5 + Starlight 0.34.
docs/site/ path is preserved so deploy workflow references still work.

Stack notes:
- Starlight ships Expressive Code (copy buttons, diffs, line highlights),
  Pagefind search, dark mode, asides, and Tabs out of the box
- Uses legacy content collections (src/content/config.ts +
  legacy.collections: true in astro.config.mjs) — required for Starlight
  0.34 SSG compatibility with the static route generator
- Sidebar autogenerates from directory rather than explicit slug entries,
  avoiding a Starlight build-time slug resolution issue on 404 page
  generation (known Starlight 0.34 limitation with content layers)
- Brand colours ported from VitePress custom.css (teal #1ad1b8, dark bg
  #071019) via Starlight CSS custom property overrides
- CommandOutput.astro: labelled two-panel card rather than Tabs — command
  and output are cause-effect pairs, not alternatives to switch between
- Hero.astro shim kept minimal (passes through to Starlight default)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: migrate all VitePress content to Starlight content collection

Port 14 pages from docs/site/ flat VitePress layout to the Starlight
content collection at docs/site/src/content/docs/:

  guide/: getting-started, validate, compare, normalize, info,
          ci-cd, ai-agents, fhir-versions
  reference/: cli, library-api, output-formats, exit-codes
  ecosystem.md, index.mdx (splash homepage with CardGrid)

Per-page changes:
- Added Starlight frontmatter (title, description, sidebar.order)
- Updated internal links from /guide/foo to /fhir-resource-diff/guide/foo/
- Homepage converted to MDX to use Starlight <Card>/<CardGrid> components
- English Canadian spelling throughout (normalise, organisation, behaviour)
- No em dashes in any externally visible text

docs.yml: run install/build from docs/site/ working directory (separate
package), output path updated from .vitepress/dist to dist, removed
VitePress-specific --fetch-depth=0 flag.

Build verified: pnpm build in docs/site/ produces 15 pages, Pagefind
indexes 14 content pages, sitemap generated.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(site): fix double base path, hero styling, and dark-mode contrast

Three targeted fixes to the Astro/Starlight migration:

1. Base path duplication (404s): All internal content links used absolute
   paths like /fhir-resource-diff/guide/... but Starlight/Astro prepends
   the configured base automatically. Stripped the prefix from every
   internal link across all 14 content files, astro.config.mjs sidebar
   entry, and the splash hero CTA.

2. Dark-mode contrast: Active sidebar items rendered solid teal background
   with near-invisible text. Replaced with a left-border + accent-text
   treatment using --sl-color-accent-low as a subtle fill, which passes
   WCAG AA in both modes. Also fixed sidebar hover, right-nav active item,
   inline code in headings, and body link colours in both themes.

3. Hero aesthetic: Added Space Grotesk Variable (@fontsource-variable) as
   a display face on the splash hero H1 only, with letter-spacing and a
   radial teal gradient backdrop behind the hero section. Copy unchanged.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* build: remove deprecated compiler options from tsconfig

* docs: migrate to shared @fhir-toolkit/docs-theme (Option B sync)

- Add shared theme files under docs/site/src/theme/ (tokens, styles, components)
  synced from packages/docs-theme via scripts/sync.js
- Wire theme-teal.css + base.css into astro.config.mjs customCss
- Remove local CommandOutput.astro duplicate
- Clear custom.css to a placeholder comment (all styles now in shared theme)
- Custom landing page (index.astro) already present; theme tokens applied

* build: restore paths alias and suppress tsup-injected baseUrl deprecation

tsup 8.x injects baseUrl when paths is configured for DTS generation.
TypeScript 6.0 treats this as a deprecation error without ignoreDeprecations.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: dnlbox

.github/workflows/docs.yml

@@ -21,8 +21,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0 # needed for VitePress git-based last-updated timestamps
 
       - uses: pnpm/action-setup@v4
 
@@ -31,12 +29,17 @@ jobs:
           node-version: "22"
           cache: pnpm
 
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm docs:build
+      - name: Install docs dependencies
+        working-directory: docs/site
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs
+        working-directory: docs/site
+        run: pnpm build
 
       - uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/site/.vitepress/dist
+          path: docs/site/dist
 
   deploy:
     environment:

docs/site/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.astro/

docs/site/.vitepress/config.ts

@@ -0,0 +1,128 @@
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+
+const HOSTNAME = "https://dnlbox.github.io/fhir-resource-diff";
+const DESCRIPTION =
+  "FHIR R4/R4B/R5 diff, validation, and comparison. TypeScript CLI and library for CI pipelines and AI agents. No server, no Java runtime.";
+
+export default defineConfig({
+  site: HOSTNAME,
+  base: "/fhir-resource-diff",
+  legacy: {
+    collections: true,
+  },
+  integrations: [
+    starlight({
+      title: "fhir-resource-diff",
+      description: DESCRIPTION,
+      social: [
+        {
+          icon: "github",
+          label: "GitHub",
+          href: "https://github.com/dnlbox/fhir-resource-diff",
+        },
+        {
+          icon: "npm",
+          label: "npm",
+          href: "https://www.npmjs.com/package/fhir-resource-diff",
+        },
+      ],
+      editLink: {
+        baseUrl:
+          "https://github.com/dnlbox/fhir-resource-diff/edit/main/docs/site/",
+      },
+      customCss: [
+        "./src/theme/tokens/theme-teal.css",
+        "./src/theme/styles/base.css",
+        "./src/styles/custom.css"
+      ],
+      sidebar: [
+        {
+          label: "Guide",
+          autogenerate: { directory: "guide" },
+        },
+        {
+          label: "Reference",
+          autogenerate: { directory: "reference" },
+        },
+        {
+          label: "Ecosystem",
+          link: "/ecosystem/",
+        },
+      ],
+      head: [
+        {
+          tag: "meta",
+          attrs: { property: "og:type", content: "website" },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:site_name",
+            content: "fhir-resource-diff",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:title",
+            content: "fhir-resource-diff — FHIR diff, validate & compare CLI",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: { property: "og:description", content: DESCRIPTION },
+        },
+        {
+          tag: "meta",
+          attrs: { property: "og:url", content: HOSTNAME + "/" },
+        },
+        {
+          tag: "meta",
+          attrs: { name: "twitter:card", content: "summary" },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            name: "twitter:title",
+            content: "fhir-resource-diff — FHIR diff, validate & compare CLI",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: { name: "twitter:description", content: DESCRIPTION },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            name: "google-site-verification",
+            content: "Ffbl73Sm-TtkxrvNsLRS417HB-VjOPRmerHZVfhF0QQ",
+          },
+        },
+        {
+          tag: "script",
+          attrs: { type: "application/ld+json" },
+          content: JSON.stringify({
+            "@context": "https://schema.org",
+            "@type": "SoftwareApplication",
+            name: "fhir-resource-diff",
+            description: DESCRIPTION,
+            applicationCategory: "DeveloperApplication",
+            operatingSystem: "Any",
+            programmingLanguage: "TypeScript",
+            url: HOSTNAME + "/",
+            downloadUrl:
+              "https://www.npmjs.com/package/fhir-resource-diff",
+            license: "https://opensource.org/licenses/MIT",
+            codeRepository:
+              "https://github.com/dnlbox/fhir-resource-diff",
+            author: { "@type": "Person", name: "Daniel Veronez" },
+          }),
+        },
+      ],
+      expressiveCode: {
+        themes: ["dark-plus", "github-light"],
+      },
+    }),
+  ],
+});

docs/site/.vitepress/theme/custom.css

@@ -0,0 +1,28 @@
+{
+  "name": "fhir-resource-diff-docs",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.34.3",
+    "@fontsource-variable/plus-jakarta-sans": "^5.2.8",
+    "@fontsource-variable/space-grotesk": "^5.2.10",
+    "astro": "^5.8.1",
+    "sharp": "^0.33.5"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "pnpm": ">=10.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "sharp"
+    ]
+  }
+}