Product docs are the skeleton key to adoption. If your README is the first touchstone and your marketing site is the second, your docs are where users actually live for the first six months. But docs are also where companies make weird choices: Notion-public-page (beautiful but slow, bad for SEO), GitBook (great design but $$$), ReadMe (beautiful but vendor lock-in), or a Markdown folder in a separate repo that no one updates.
There's a third way. If you're already building your marketing site with Astro — which most modern product teams are doing by 2026 — Astro Starlight lets you ship production-grade docs as a subroute of the same project. Same framework, same build pipeline, zero extra infrastructure. Your docs live at `/docs` in the same place your pricing lives at `/pricing`. They're versioned with your code. They're AI-readable. Your CI/CD handles both. No SaaS subscription. One codebase. That's the move.
What Starlight Actually Is
Starlight is an Astro integration — a pre-built documentation site. It's 0.37.x at time of writing. What it does: takes a folder of Markdown/MDX files, auto-generates a sidebar from the folder structure, auto-wires search with Pagefind (no API keys), renders each page with a two-column layout (sidebar + content), and handles responsive mobile nav.
Setup is 3 npm install + 1 config line:
{`npm install @astrojs/starlight
# astro.config.mjs
integrations: [
starlight({
title: 'Velocity X Docs',
sidebar: [
{ label: 'Getting Started', autogenerate: { directory: 'getting-started' } },
{ label: 'API', autogenerate: { directory: 'api' } },
{ label: 'Guides', autogenerate: { directory: 'guides' } },
],
}),
]`}The `autogenerate` rule reads your folder structure and wires up the sidebar links automatically. Add a new Markdown file in `docs/getting-started/` and it's live with zero config.
Why This Beats Alternatives
vs. Notion-public-page: Notion is beautiful but uses JavaScript to render. Google crawls it, but it's slow. Starlight is static HTML, fast, and includes structured data for SEO by default. Notion also doesn't auto-update when you change the page — Starlight updates on every deploy.
vs. GitBook: GitBook charges $80–$150/month for a team and their free tier is slow. Starlight is zero cost if you're already on Netlify. Your docs build as part of your main site build; no separate pipeline, no separate hosting.
vs. ReadMe: ReadMe is slick and they have good integrations (Slack, API explorer). But you're locked in. If you want to move your docs later, you're exporting Markdown and rebuilding. Starlight keeps you portable — all your content is plain Markdown, your styling is CSS you control, your deployment is your own CI/CD.
vs. separate docs repo: A lot of teams keep docs in a different repo, forget to update it, and ship stale docs. Starlight being in the same project as your code makes the mental model stick. Docs and code evolve together. One PR updates both.
Integration with Your Marketing Site
The key move: Starlight and your marketing site share the same header, navigation context, and DNS. You define your header once in `src/components/layout/HeaderApp.tsx`, Starlight uses it. Your users don't bounce between two different nav systems.
Styling diverges intentionally. Your marketing site is design-forward. Your docs are content-forward. Starlight includes a dark mode toggle out of the box (Alpine-driven, uses the same `$store.theme.isDark` as your marketing site). The docs sidebar has different spacing and typography than your marketing grid because they serve different cognitive loads.
The Velocity X setup: docs live at `src/content/docs/` (Starlight convention), marketing site at `src/pages/`. Both build into the same deploy. Both push to the same Netlify. Your branch previews include both simultaneously.
Search, Versioning, and AI Readiness
Starlight ships with Pagefind, a client-side search engine. Users type in the `/docs` search box, no API calls, search works offline. You don't need to maintain a search backend.
For versioning: docs live in git like code. If you shipped a breaking API change on v2, you can keep v1 docs in a `docs-v1/` folder and serve both. Starlight doesn't auto-handle versions, but you can configure separate sidebar trees per version and route to the right one. Most teams don't version until docs get big enough that versioning matters; Starlight gets you there if you need it.
AI readiness: Starlight renders semantic HTML with clear H2/H3 hierarchy. No JavaScript-rendered content blocking the copy. Claude and other assistants can read your docs in the raw — and if you're shipping an AI-integrated product, your docs are part of your API contract. Clean structure matters.
The Catch
Starlight is opinionated. If you want a completely custom doc layout, you'll either use Starlight's override system (doable but fiddly) or you'll eject and build your own. For standard docs (sidebar + content + search + mobile nav), Starlight is the right call. For something unusual, you're better off rolling your own Astro setup.
MDX is powerful but slower to build than plain Markdown if your docs are huge (100+ pages). Most product docs are fine. If you're shipping 500-page docs, split them across multiple Astro projects or accept that your build time will creep toward 60s.
Pagefind search is excellent but doesn't have relevance tuning the way Algolia does. It's good enough for 95% of product docs. If search is a major user-facing feature of your docs, Algolia is still the right call.
The Verdict
If you're building a modern product in 2026 and you're using Astro for your marketing site, Starlight is the only sane choice for docs. It's free, it's fast, it's built for the web, and it keeps your content versioned with your code. Every minute you spend setting up Starlight is a minute you don't spend managing Notion, paying GitBook, or watching ReadMe slow down your load times. Your docs are too important to lock into a SaaS. Ship them alongside your site.
If you want to see Starlight in production, check the Velocity X docs or read the pricing page to understand how docs feed into your product narrative.