docs: migrate docs to Astro Starlight

Author: aallam

.gitignore

@@ -2,8 +2,7 @@
 node_modules/
 .npm-cache/
 dist/
-docs/.vitepress/cache/
-docs/.vitepress/dist/
+docs/.astro/
 packages/*/dist/
 packages/*/temp/
 coverage/

README.md

@@ -33,5 +33,5 @@ Runnable examples live in [`examples/`](./examples/) and are indexed in [`exampl
 ## Docs
 
 - [Public Docs](https://execbox.aallam.com)
-- [Getting Started Guide](./docs/getting-started.md)
-- [Execbox Architecture Overview](./docs/architecture/README.md)
+- [Getting Started Guide](./docs/src/content/docs/getting-started.md)
+- [Execbox Architecture Overview](./docs/src/content/docs/architecture/index.md)

docs/.vitepress/config.ts

@@ -0,0 +1,76 @@
+import starlight from "@astrojs/starlight";
+import { defineConfig } from "astro/config";
+import mermaid from "astro-mermaid";
+
+export default defineConfig({
+  site: "https://execbox.aallam.com",
+  integrations: [
+    mermaid({
+      autoTheme: true,
+      enableLog: false,
+      mermaidConfig: {
+        securityLevel: "loose",
+      },
+    }),
+    starlight({
+      title: "execbox",
+      description:
+        "Portable code execution for MCP tools and wrapped MCP servers.",
+      customCss: ["/src/styles/custom.css"],
+      lastUpdated: true,
+      pagefind: true,
+      social: [
+        {
+          icon: "github",
+          label: "GitHub",
+          href: "https://github.com/aallam/execbox",
+        },
+      ],
+      sidebar: [
+        {
+          label: "Start",
+          items: [
+            { label: "Overview", link: "/" },
+            { label: "Getting Started", slug: "getting-started" },
+            { label: "Runtime Choices", slug: "runtime-choices" },
+          ],
+        },
+        {
+          label: "Use",
+          items: [
+            { label: "Examples", slug: "examples" },
+            {
+              label: "MCP Provider",
+              slug: "architecture/execbox-mcp-and-protocol",
+            },
+            {
+              label: "Remote Runner",
+              slug: "architecture/execbox-remote-workflow",
+            },
+          ],
+        },
+        {
+          label: "Understand",
+          items: [
+            { label: "Security", slug: "security" },
+            { label: "Architecture", slug: "architecture" },
+            { label: "Performance", slug: "performance" },
+          ],
+        },
+        {
+          label: "Reference",
+          items: [
+            {
+              label: "Protocol",
+              slug: "architecture/execbox-protocol-reference",
+            },
+            {
+              label: "Runner Specification",
+              slug: "architecture/execbox-runner-specification",
+            },
+          ],
+        },
+      ],
+    }),
+  ],
+});

docs/.vitepress/theme/custom.css

@@ -0,0 +1,7 @@
+import { defineCollection } from "astro:content";
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

docs/.vitepress/theme/index.ts

@@ -1,4 +1,7 @@
-# Execbox Core Architecture
+---
+title: Execbox Core Architecture
+description: Provider resolution, execution contracts, shared runner semantics, and errors in execbox core.
+---
 
 This page covers the parts of execbox that stay stable regardless of which executor package you choose.