docs: migrate to Astro Starlight documentation site

.github/instructions/doc-sync.instructions.md

@@ -5,7 +5,7 @@ description: "Rules to keep documentation synchronized with code changes"
 
 # Rules to keep documentation up-to-date
 
-- Rule 1: Whenever changes are made to the codebase, it's important to also update the documentation to reflect those changes. You must ensure that the following documentation is updated: [.md files in the docs directory](../../docs/). You can simply update the above markdown files to match the changes in the codebase. 
+- Rule 1: Whenever changes are made to the codebase, it's important to also update the documentation to reflect those changes. You must ensure that the following documentation is updated: [Starlight content pages in docs/src/content/docs/](../../docs/src/content/docs/). Each page uses Starlight frontmatter (title, sidebar order). Cross-page links use relative paths (e.g., `../../guides/compilation/`).
 
 - Rule 2: The main [README.md](../../README.md) file is a special case that requires user approval before changes, so, if there is a deviation in the code that affects what is stated in the main [README.md](../../README.md) file, you must warn the user and describe the drift and [README.md](../../README.md) update proposal, and wait for confirmation before updating it. 
 

.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**']
+  pull_request:
+    paths: ['docs/**']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages-${{ github.ref }}"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: 'docs/package-lock.json'
+
+      - name: Install dependencies
+        working-directory: ./docs
+        run: npm ci
+
+      - name: Build documentation
+        working-directory: ./docs
+        run: npm run build
+
+      - name: Upload build artifacts
+        if: github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/dist
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

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

docs/astro.config.mjs

@@ -0,0 +1,104 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import starlightLlmsTxt from 'starlight-llms-txt';
+import starlightLinksValidator from 'starlight-links-validator';
+import mermaid from 'astro-mermaid';
+
+// https://astro.build/config
+export default defineConfig({
+	site: 'https://microsoft.github.io',
+	base: '/apm/',
+	integrations: [
+		mermaid(),
+		starlight({
+			title: 'Agent Package Manager',
+			description: 'An open-source, community-driven dependency manager for AI agents. Declare skills, prompts, instructions, and tools in apm.yml — install with one command.',
+			favicon: '/favicon.svg',
+			social: [
+				{ icon: 'github', label: 'GitHub', href: 'https://github.com/microsoft/apm' },
+			],
+			tableOfContents: {
+				minHeadingLevel: 2,
+				maxHeadingLevel: 4,
+			},
+			pagination: true,
+			customCss: ['./src/styles/custom.css'],
+			expressiveCode: {
+				frames: {
+					showCopyToClipboardButton: true,
+				},
+			},
+			plugins: [
+				starlightLinksValidator({
+					errorOnRelativeLinks: false,
+					errorOnLocalLinks: true,
+				}),
+				starlightLlmsTxt({
+					description: 'APM (Agent Package Manager) is an open-source dependency manager for AI agents. It lets you declare skills, prompts, instructions, agents, hooks, plugins, and MCP servers in a single apm.yml manifest, resolving transitive dependencies automatically.',
+				}),
+			],
+			sidebar: [
+				{
+					label: 'Understanding APM',
+					items: [
+						{ label: 'What is APM?', slug: 'introduction/what-is-apm' },
+						{ label: 'Why APM?', slug: 'introduction/why-apm' },
+						{ label: 'How It Works', slug: 'introduction/how-it-works' },
+						{ label: 'Key Concepts', slug: 'introduction/key-concepts' },
+					],
+				},
+				{
+					label: 'Getting Started',
+					items: [
+						{ label: 'Installation', slug: 'getting-started/installation' },
+						{ label: 'Quick Start', slug: 'getting-started/quick-start' },
+						{ label: 'Your First Package', slug: 'getting-started/first-package' },
+						{ label: 'Authentication', slug: 'getting-started/authentication' },
+						{ label: 'Migrating Projects', slug: 'getting-started/migration' },
+					],
+				},
+				{
+					label: 'Guides',
+					items: [
+						{ label: 'Compilation & Optimization', slug: 'guides/compilation' },
+						{ label: 'Skills', slug: 'guides/skills' },
+						{ label: 'Prompts', slug: 'guides/prompts' },
+						{ label: 'Plugins', slug: 'guides/plugins' },
+						{ label: 'Dependencies & Lockfile', slug: 'guides/dependencies' },
+						{ label: 'Pack & Distribute', slug: 'guides/pack-distribute' },
+						{ label: 'Org-Wide Packages', slug: 'guides/org-packages' },
+					],
+				},
+				{
+					label: 'Enterprise',
+					items: [
+						{ label: 'APM for Teams', slug: 'enterprise/teams' },
+						{ label: 'Governance & Compliance', slug: 'enterprise/governance' },
+						{ label: 'Security Model', slug: 'enterprise/security' },
+						{ label: 'Adoption Playbook', slug: 'enterprise/adoption-playbook' },
+						{ label: 'Making the Case', slug: 'enterprise/making-the-case' },
+					],
+				},
+				{
+					label: 'Integrations',
+					items: [
+						{ label: 'CI/CD Pipelines', slug: 'integrations/ci-cd' },
+						{ label: 'GitHub Agentic Workflows', slug: 'integrations/gh-aw' },
+						{ label: 'IDE & Tool Integration', slug: 'integrations/ide-tool-integration' },
+						{ label: 'AI Runtime Compatibility', slug: 'integrations/runtime-compatibility' },
+						{ label: 'GitHub Rulesets', slug: 'integrations/github-rulesets' },
+					],
+				},
+				{
+					label: 'Reference',
+					autogenerate: { directory: 'reference' },
+				},
+				{
+					label: 'Contributing',
+					autogenerate: { directory: 'contributing' },
+				},
+			],
+		}),
+	],
+});