Repository navigation
Conversation
An Astro + Starlight site in website/ copies docs/, AGENTS.md and the config files in at build time, so the repository stays the single source. The sync step strips each page's H1 into the title, rewrites relative links to site pages or GitHub URLs, takes lastUpdated from git, and derives workspace and single-crate lint snippets plus downloadable files from the real configs.
The quick start offers a do-it-yourself path with synced Workspace and Single crate tabs, and a one-prompt path for coding agents. Snippets are generated from the real configs. It shows the warnings a fresh cargo new project produces and how to fix them, CI wiring, troubleshooting with the exact messages users will see, and how to remove the kit. Also fixes the lint snippet extraction to match table headers only and expands section anchors into full guide URLs.
…disclaimer astro-mermaid renders the Mermaid diagrams from the repo docs with theme switching. starlight-links-validator fails the build on broken internal links or anchors, and a footer override states on every page that the kit is not affiliated with Google.
Each answer opens with a direct one-sentence answer and links to the page with the details, so search snippets and answer engines can quote it.
@astrojs/sitemap replaces Starlight's built-in sitemap so <lastmod> comes from the git history of each page's source. starlight-llms-txt publishes llms.txt, llms-full.txt, llms-small.txt and two topic sets: one for coding agents (the quick start prompt points to it) and one for reviewers. starlight-page-actions adds a .md twin of every page with copy and open-in-assistant buttons. It is configured without baseUrl so it does not overwrite llms.txt. The quick start and landing page now use plain fenced code blocks, so their markdown twins contain the real commands.
astro-og-canvas renders a 1200x630 social image per page. A Starlight route middleware adds og:image and twitter:image, a rel=alternate link to each page's markdown twin, and JSON-LD: SoftwareSourceCode on the home page, TechArticle plus BreadcrumbList elsewhere, with dateModified from git. No WebSite node, because Google does not show site names for subdirectory sites.
withastro/action builds website/ with bun, including astro check and link validation. Pull requests only build; pushes to main also deploy through actions/deploy-pages. The checkout fetches full history because page dates and sitemap lastmod come from git.
… prompt A rust-orange accent replaces Starlight's default in both themes, keeping light-mode link contrast above 5:1. The agent prompt wraps instead of scrolling, and the open-in-assistant buttons ask the assistant to help apply the kit rather than only answer questions.
The verify step runs clippy with -D warnings, so a fresh project reports errors, not warnings. The page now matches what users see and notes that a binary crate needs a crate-level doc comment too. Both were found by following the quick start on a fresh single crate and a fresh workspace.
…nt bundle Starlight's file tree comments measured 4.48:1 on the dark code background; a site-level override lifts them above 4.5:1, and Lighthouse now scores 100 for accessibility on the quick start and landing page. The agent tab no longer claims the bundle contains every config file, which a test agent pointed out.
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved critical workflow permission exposure and destructive cleanup instructions, along with additional documented correctness issues, block approval.
2 open issues
What changed in this PR
This pull request adds an Astro + Starlight website that publishes the Rust style guide kit, documentation, configuration files, adoption guidance, and agent-oriented resources through GitHub Pages.
Changes:
- Adds the Starlight site, themed documentation, quick start, FAQ, downloadable files, search, SEO metadata, JSON-LD, and social images.
- Synchronizes repository documentation and configuration into generated site content at build time.
- Adds GitHub Pages CI/CD and links the published site from the README.
| File | Description |
|---|---|
website/tsconfig.json |
Configures strict TypeScript checking for the Astro site. |
website/src/styles/theme.css |
Defines Rust-themed Starlight colors and file-tree styling. |
website/src/route-middleware.ts |
Adds social metadata, Markdown alternates, and structured data. |
website/src/pages/og/[...route].ts |
Generates per-page Open Graph images. |
website/src/content/docs/quick-start.mdx |
Provides the four-step adoption workflow, troubleshooting, and removal guidance. |
website/src/content/docs/index.mdx |
Adds the landing page and adoption overview. |
website/src/content/docs/faq.md |
Adds adoption, tooling, and kit-behavior FAQs. |
website/src/content.config.ts |
Configures the Starlight documentation collection. |
website/src/components/Footer.astro |
Adds the unofficial-project and affiliation disclaimer. |
website/src/assets/logo.svg |
Provides the site logo. |
website/site.config.ts |
Centralizes site, repository, guide, and author metadata. |
website/public/favicon.svg |
Adds the browser favicon. |
website/package.json |
Defines Astro, Starlight, validation, and site dependencies. |
website/integrations/sync-repo-content.ts |
Synchronizes repository documentation and configuration files into the site. |
website/content-map.ts |
Maps repository sources to site pages and downloads. |
website/astro.config.ts |
Configures Astro, Starlight, sitemap, validation, Mermaid, LLM output, and page actions. |
website/.gitignore |
Excludes generated site content and build artifacts. |
README.md |
Links the repository documentation to the published website. |
.github/workflows/pages.yml |
Builds and deploys the site through GitHub Pages. |
Review effort: Lite
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
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.
Summary
Publishes the kit as a website at https://daniakash.github.io/Google-Rust-Style-Guide/, built with Astro + Starlight from the files already in this repository. The site's first job is adoption: a five-minute quick start that takes someone from "found it" to a green
cargo clippy, with a one-prompt path for coding agents. It is also set up to be found by search engines, answer engines and agents.What's in it
Adoption
/quick-start/in four steps, with synced Workspace / Single crate tabs that remember the choice:cargo newproject shows, and the three-line fixSingle source
website/integrations/sync-repo-content.tscopiesdocs/*.md,AGENTS.mdand the configs in at build time, so nothing is duplicated:lastUpdatedfrom gitworkspace-lints.toml/crate-lints.tomlfromCargo.toml, with guide anchors expanded to full URLs, and serves every config under/files/.Discoverability
@astrojs/sitemap:<lastmod>taken from git.starlight-llms-txt:llms.txt,llms-full.txt,llms-small.txt, plus "for coding agents" and "for reviewers" sets.starlight-page-actions: a.mdtwin of every page, plus Copy Markdown and Open in ChatGPT / Claude / Perplexity / Cursor buttons. Configured withoutbaseUrlso it does not overwritellms.txt.astro-og-canvas: a social image per page.og:image, arel=alternatemarkdown link, and JSON-LD (SoftwareSourceCode on the home page, TechArticle + BreadcrumbList elsewhere).<title>s and answer-first descriptions.Quality gates
astro checkandstarlight-links-validator(links and anchors) run in every build.astro-mermaidrenders the existing diagrams.CI:
.github/workflows/pages.ymlbuilds on pull requests and deploys to GitHub Pages frommain. It useswithastro/actionwithpath: websiteand fetches full history for git dates.Verification (local)
astro check0 errors / 0 warnings / 0 hints; all internal links valid; 15 pages..mdtwin and OG image.llms.txtfollows the llmstxt.org format. Every/files/*download is byte-identical to the repo file. Unknown paths return 404.-D warningsandcargo denyall went green, and every config file was left byte-identical.After merge
gh api -X POST repos/DaniAkash/Google-Rust-Style-Guide/pages -f build_type=workflow. The deploy job needs this before it can publish.sitemap-index.xml; then import into Bing Webmaster Tools.