Scaffold Starlight docs site and migrate content#1759
Draft
kmcginnes wants to merge 14 commits intofeat/starlight-docsfrom
Draft
Scaffold Starlight docs site and migrate content#1759kmcginnes wants to merge 14 commits intofeat/starlight-docsfrom
kmcginnes wants to merge 14 commits intofeat/starlight-docsfrom
Conversation
- Add graph-explorer-docs package with Astro + Starlight - Configure site URL and base path for GitHub Pages - Set up sidebar with autogenerated sections - Add docs:dev and docs:build scripts to root - Exclude docs from global build/dev commands - Allow sharp in onlyBuiltDependencies
- Convert 24 markdown files from docs/ to packages/docs/src/content/docs/ - Add frontmatter with titles extracted from first headings - Convert GFM admonitions to Starlight syntax (:::tip, :::note, :::caution) - Move images to src/assets/ for Astro optimization - Move static downloads (scripts, JSON) to public/ - Move architecture.md and development.md into references/ - Update image and file paths for new directory structure
- Deploy to GitHub Pages on push to main when packages/docs/ changes - Use pnpm/action-setup and actions/deploy-pages - Support manual workflow_dispatch trigger - Configure concurrency to prevent parallel deployments
- Replace docs/ contents with redirect README pointing to deployed site - Update root README links to use https://aws.github.io/graph-explorer/ - Keep root README images/ untouched (serves GitHub repo landing page)
- Remove manual breadcrumb links (Starlight has built-in breadcrumbs) - Remove duplicate H1 headings (frontmatter title renders as h1) - Fix broken link to development.md (moved to references/) - Fix cross-repo links to use GitHub URLs (samples, ROADMAP) - Fix self-referencing paths in references/development.md - Move HTML-referenced images to public/ for correct resolution
- Upgrade to Astro 6.1.6 + Starlight 0.38.3 (fixes moderate XSS vuln) - Pin all dependency versions to exact (matching monorepo convention) - Pin GitHub Actions to commit SHAs (matching unit.yml pattern) - Add workflow file to path trigger filter - Add step names to workflow for readability - Add description frontmatter to all 24 content pages - Convert .md links to slug-style paths (Starlight routing) - Fix static file links in troubleshooting.md - Use relative path in hero link instead of hardcoded base - Match package version to other packages (3.0.3) - Update content.config.ts for Astro 6 loader API
Move ECS Fargate images from src/assets/ and public/assets/ into src/content/docs/guides/_images/ so they live alongside the content. Convert HTML img tags to markdown for consistent Astro processing.
Move static downloads (JSON policies, shell script) from public/ into _assets/ alongside images. Replace all hardcoded /graph-explorer/ asset paths with relative references. Remove empty public/ directory.
Convert deploy-to-sagemaker and troubleshooting to .mdx and render the shell script and JSON policies as syntax-highlighted code blocks with copy buttons via raw imports and <Code> component.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Scaffolds a Starlight (Astro) documentation site in
packages/docs/and migrates all existing documentation fromdocs/.graph-explorer-docspackage with Astro + Starlightdocs:devanddocs:buildroot scripts; exclude docs from globalbuild/devsrc/assets/and static downloads topublic/docs/with redirect README and update root README linksValidation
pnpm docs:buildexits 0 and produces 25 pagespnpm buildstill works (docs excluded)pnpm testpasses all 1680 testspnpm docs:dev) renders all pages with working navigation and searchRelated Issues
Check List
pnpm checkspasses with no errors.pnpm testpasses with no failures.