Migrate documentation to Starlight (Astro)

[kmcginnes]

Description

Graph Explorer documentation currently lives as plain Markdown files in the docs/ directory. These files are only viewable by browsing the repo on GitHub — there is no deployed documentation site with search, navigation, or a polished reading experience.

We want to migrate the documentation to Starlight (an Astro-based documentation framework) and deploy it to GitHub Pages at https://aws.github.io/graph-explorer/.

Problem Statement

Users and contributors must navigate raw Markdown files on GitHub to find documentation. There is no search, no sidebar navigation, no mobile-friendly layout, and no way to discover content without knowing the file structure. The reading experience is fragmented and does not match the quality of the product itself.

Solution

Build a Starlight-powered documentation site that:

• Provides full-text search, sidebar navigation, dark/light mode, and responsive design out of the box
• Deploys automatically to GitHub Pages on every push to main
• Uses Tailwind CSS for any custom styling
• Lives in the monorepo as packages/docs/ (package name: graph-explorer-docs)
• Migrates all 25 existing Markdown files from docs/ with no content loss

User Stories

1. As a user, I want to search the documentation by keyword, so that I can quickly find relevant information without browsing the file tree.
2. As a user, I want sidebar navigation organized by topic, so that I can discover related pages and understand the documentation structure.
3. As a user, I want to read documentation on mobile, so that I can reference guides while working in a different environment.
4. As a user, I want dark and light mode, so that the docs match my system preference.
5. As a contributor, I want to preview documentation changes locally with hot reload, so that I can iterate quickly on content.
6. As a contributor, I want documentation to deploy automatically when my PR merges, so that I do not need to perform manual deployment steps.
7. As a contributor, I want the docs project to follow the same monorepo conventions (pnpm, workspace packages), so that the workflow is familiar.
8. As a user, I want the deployed site to be the canonical documentation URL referenced from the README, so that I always find the latest version.
9. As a maintainer, I want the docs build to be excluded from the global pnpm build and pnpm dev, so that it does not slow down application development.
10. As a maintainer, I want dedicated docs:dev and docs:build scripts at the root, so that working on docs is a single command.
11. As a user, I want admonitions (tips, notes, cautions) to render with clear visual styling, so that important information stands out.
12. As a user, I want the getting-started tutorial to be easy to find from the landing page, so that I can onboard quickly.

Implementation Decisions

• Scaffold via official template: Use pnpm create astro --template starlight/tailwind to create the project in packages/docs/. This ensures we start from the official blessed configuration rather than hand-rolling files.
• Tailwind CSS: Included via the starlight/tailwind template. Start with default Starlight theme; custom branding is deferred.
• Sidebar: Autogenerated from directory structure using Starlight's autogenerate config. Page ordering controlled via sidebar.order frontmatter.
• Content structure: Maps existing docs/ hierarchy into src/content/docs/ with directories: getting-started/, features/, guides/, references/. The standalone development.md and architecture.md move into references/.
• Admonition conversion: GitHub-flavored > [!TIP] syntax converted to Starlight :::tip syntax (12 occurrences across 8 files).
• Assets: Images go to src/assets/ (Astro-optimized). Shell scripts and JSON policy files go to public/ (served as static downloads).
• Deployment: GitHub Actions workflow deploys to GitHub Pages on push to main with a path filter on packages/docs/**. Uses pnpm/action-setup, actions/setup-node, and actions/deploy-pages.
• Base path: base: "/graph-explorer" in Astro config since the site is hosted at a subpath.
• Monorepo integration: Docs package excluded from global build/dev scripts via --filter "!graph-explorer-docs". Dedicated docs:dev and docs:build added to root.
• Old docs cleanup: docs/ directory replaced with a single README pointing to the deployed site. Root README links updated to deployed URLs.
• Root README and images/: Left untouched — they serve the GitHub repo landing page independently.
• Versioning: Deferred. Can be added later via the starlight-versions plugin.

Testing Decisions

This is a documentation infrastructure project with no application logic. Testing is limited to:

• Build verification: The site builds successfully (pnpm docs:build exits 0)
• Link validation: Internal links resolve correctly (can be verified manually or with a link checker in CI later)
• Visual verification: Pages render correctly in the dev server during development

No unit tests are needed. The GitHub Actions workflow itself serves as the integration test — if the build fails, deployment is blocked.

Out of Scope

• Custom branding / color theme (deferred to follow-up)
• Versioned documentation (deferred; starlight-versions plugin available when needed)
• Auto-generated API/TypeScript documentation from source code
• Migrating Changelog, ROADMAP, or CONTRIBUTING into the docs site
• Embedded live demos or interactive components
• Internationalization (i18n)

Further Notes

• The existing docs total ~25 Markdown files and ~50KB of prose — small enough for a one-shot migration.
• Starlight provides built-in Pagefind search with zero configuration.
• The packages/* glob in pnpm-workspace.yaml already covers packages/docs/ — no workspace config change needed.
• GitHub Pages must be enabled in repo settings with source set to "GitHub Actions" before the first deploy will work.

High-Level Plan

1. Scaffold Starlight project using official template
2. Configure Astro (site, base path, sidebar, Tailwind)
3. Migrate content (frontmatter, admonitions, assets, links)
4. Integrate with monorepo (scripts, exclusions)
5. Add GitHub Actions deployment workflow
6. Clean up old docs/ and update README links