Static Site Generators in Production

Docusaurus vs Starlight for Product Documentation

Product documentation has a specific shape: several hundred task and reference pages, a changelog, an API section, frequent small edits by writers and support staff, and readers who arrive from search on a phone with one question. Both Docusaurus and Starlight handle that shape; the question is which one handles it cheaply over years. This comparison ports one real site — 640 pages of SaaS product docs with 210 screenshots, 48 embedded code tabs and 3 interactive API playgrounds — to both, and measures what changes.

The wider three-way picture, including VitePress, is in Docs Frameworks: Docusaurus, Starlight and VitePress.

Prerequisites

  • Node.js 20 or later and a content set in Markdown or MDX with front matter.
  • A Lighthouse CI setup or equivalent to measure every build the same way — see Setting Up Lighthouse CI for a Static Site.
  • Real-user monitoring for INP if you want field numbers rather than lab estimates.
  • Roughly two engineer-days per framework for a port of this size, most of it spent on custom components.

The Port, Step by Step

The site started on Docusaurus 3.8 with the classic theme and six swizzled components. The Starlight port followed four steps.

1. Scaffold and move content. npm create astro@latest -- --template starlight produces src/content/docs/. The 640 files moved across unchanged except for front matter: Docusaurus's sidebar_position became Starlight's sidebar: { order: n }, done with a forty-line script of the kind described in Converting Front Matter at Scale During Migration.

2. Replace admonitions and tabs. Docusaurus :::note admonitions work unchanged in Starlight, which supports the same directive syntax as asides. The <Tabs>/<TabItem> imports needed rewriting to Starlight's <Tabs>/<TabItem> from @astrojs/starlight/components — same names, different import path, so a codemod handled all 48.

3. Rebuild the sidebar. Docusaurus's sidebars.js was translated into Starlight's sidebar config, using autogenerate: { directory: 'guides' } for four of the six sections so new pages appear without config edits.

4. Port the playgrounds. The three API playgrounds were React components. They kept working through @astrojs/react with client:visible, so their JavaScript loads only when scrolled into view — the pattern from Deferring Hydration with client:visible in Astro.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import react from '@astrojs/react';

export default defineConfig({
  site: 'https://docs.example.com',
  trailingSlash: 'always',
  integrations: [
    starlight({
      title: 'Example Docs',
      editLink: { baseUrl: 'https://github.com/example/docs/edit/main/' },
      sidebar: [
        { label: 'Start here', autogenerate: { directory: 'start' } },
        { label: 'Guides', autogenerate: { directory: 'guides' } },
        { label: 'API', autogenerate: { directory: 'api' } },
      ],
      customCss: ['./src/styles/brand.css'],
    }),
    react(),
  ],
});
Where the porting effort went A bar chart of engineer hours spent on the port by task. Moving content took 2 hours, front matter conversion 3 hours, tabs and admonitions 2 hours, the sidebar 3 hours, the React playgrounds 4 hours and restyling to the brand 6 hours, for 20 hours in total. 20 engineer-hours, mostly outside the prose Move 640 files 2 h Front matter script 3 h Tabs + admonitions 2 h Sidebar config 3 h React playgrounds 4 h Brand restyle 6 h Time-tracked port of a 640-page product docs site; prose itself needed no edits
The prose moved for free. The time went on the things that are framework-specific: styling, components and navigation.

Measured Impact

Both builds ran on the same GitHub Actions runner; page metrics are Lighthouse 12 mobile medians over five runs of four templates; field INP comes from web-vitals beacons over two four-week windows with similar traffic (about 180,000 page views each).

MetricDocusaurus 3.8Starlight 0.34Change
Cold build (hyperfine, 5 runs)58 s27 s−53%
Warm build, one page edited44 s12 s−73%
Compressed JS, median page186 KB9 KB (41 KB on playground pages)−95%
Lab LCP, simulated 4G2.0 s1.0 s−50%
Field INP, p75210 ms96 ms−54%
Field LCP, p751.9 s1.3 s−32%
Deploy artifact size92 MB38 MB−59%
Field INP and LCP before and after the port Paired bars from real-user monitoring at the 75th percentile. INP fell from 210 milliseconds on Docusaurus to 96 on Starlight, crossing below the 200 millisecond good threshold. LCP fell from 1.9 seconds to 1.3 seconds, both under the 2.5 second threshold. Real users, p75, four weeks each INP (ms) 200 ms threshold 210 96 Docusaurus Starlight LCP (s) 2.5 s threshold 1.9 1.3 Docusaurus Starlight web-vitals beacons, ~180,000 page views per window
INP moved from "needs improvement" to "good" without touching a single interaction handler — the change was simply shipping less JavaScript.

The INP result is the one that mattered to the business: Search Console had flagged 312 URLs as "INP needs improvement" on mobile, and 28 days after launch that count was zero. The field breakdown is explained in Measuring INP on Static Sites with Real-User Monitoring.

Where Docusaurus Still Won

The comparison was not one-sided, and three things were genuinely harder on Starlight.

Versioning. The product kept two supported versions. On Docusaurus that was docs:version and a dropdown. On Starlight it became two branches, two deploys (/docs/ and /docs/v1/) and a custom Header override with a version switcher — about six hours of extra work, and a second build pipeline to maintain. Teams with four or more live versions should weigh that heavily; the Docusaurus approach is covered in Versioned Documentation with Docusaurus.

Plugin breadth. Docusaurus has a larger plugin catalogue: OpenAPI page generation, ideal-image, PWA, client redirects. Starlight's catalogue is growing but thinner, and the OpenAPI plugin needed configuration work to match the old output.

Blog. The changelog had been a Docusaurus blog with tags and an RSS feed. It moved to the starlight-blog community plugin, which worked but required restyling.

Scorecard across six criteria Six criteria scored from one to five for each framework. Page weight: Docusaurus 2, Starlight 5. Build speed: 2 and 4. Authoring ease: 3 and 5. Versioning: 5 and 2. Plugin breadth: 5 and 3. Upgrade stability: 4 and 3. Six criteria, scored 1 to 5 for this site Docusaurus Starlight Page weight Build speed Authoring ease Versioning Plugin breadth Upgrade stability Totals Docusaurus 21 / 30 Starlight 22 / 30 Near-tie overall: the weighting you give versioning decides it
Unweighted, the two are within a point. Weight page weight and authoring for a support-driven docs site and Starlight wins; weight versioning for an enterprise product and Docusaurus does.

Authoring and Review After the Switch

Performance numbers convinced the engineering lead; the writers were convinced by what happened to their daily loop. Three changes stood out in the month after launch.

Faster local preview. astro dev started in 1.8 seconds against 11 seconds for docusaurus start, and hot reload on a Markdown save dropped from about 2.5 seconds to under half a second. For a writer saving forty times an hour, that is the difference between watching the preview and forgetting it exists.

Readable errors. The most common Docusaurus failure had been an MDX compile error caused by an unescaped < or { in prose — for example latency < 200ms or a JSON snippet outside a code fence. Starlight parses .md files as plain Markdown, so those characters simply render. The support team, who contribute about a quarter of all edits, stopped filing "the build is broken" tickets entirely; there had been eleven in the previous quarter.

Smaller review diffs. Autogenerated sidebars removed a class of pull request in which a writer added a page and forgot to register it in sidebars.js. Reviews became content-only, and median time from pull request to merge fell from 26 hours to 17 over the following six weeks, measured from the GitHub API.

None of this is exclusive to Starlight — a well-configured Docusaurus with format: 'detect' and autogenerated sidebars recovers part of it — but defaults matter because most teams never change them. If writer experience is a priority, audit the defaults with the same care as the build numbers, using the review workflow in Docs-as-Code Review Workflow for Writers as the baseline.

Search behaviour changed too. Pagefind loads index fragments on demand, so the first query on a page costs about 90 KB of downloads and returns in roughly 150 ms on a mid-range phone; Algolia had answered in about 60 ms from its API. Nobody noticed in usability sessions, but it is a measurable difference, and it is worth recording in the decision log so that a future complaint about search speed can be traced to a deliberate trade rather than a regression.

Pitfalls & Rollback

  • Assuming admonitions port cleanly everywhere. Docusaurus's :::note[Title] title syntax differs slightly from older Starlight releases; grep for ::: with a bracket and test a sample.
  • Dropping redirects. Docusaurus's /docs/ prefix disappeared in the new URL scheme on the first attempt. Keep URLs identical or generate redirects as described in Keeping Redirects Working After an SSG Migration.
  • Hydrating everything. Wrapping every React component in client:load recreates the Docusaurus JavaScript bill. Default to no directive; add client:visible only to components that respond to input.
  • Losing search analytics. Moving from Algolia to Pagefind removes Algolia's query analytics. Log searches to your own endpoint if the support team relies on them.
  • Rollback: run both sites in parallel behind the same domain during cutover, routing by path prefix at the CDN. Reverting is a routing change, and the old build stays deployable until the new one has four clean weeks of field data.

Conclusion

For this product's docs, Starlight halved build time, cut JavaScript by 95% and moved field INP from 210 ms to 96 ms, at the cost of hand-assembling versioning and a thinner plugin catalogue. That trade is right for most support-driven documentation with one or two live versions. For products with many supported versions, a built-in blog and a React-heavy design system, Docusaurus's integrated features still earn their runtime cost — especially with Rspack enabled to close the build-time gap.

FAQ

Is Starlight mature enough for a commercial product's docs?

For most product documentation, yes. It is pre-1.0, so minor releases can include breaking changes, but those are documented in the changelog and in our port each upgrade took under an hour. Pin exact versions and upgrade through a preview deploy.

When is Docusaurus clearly the better choice?

When you need several concurrently supported doc versions, a built-in blog, or deep integration with an existing React design system. Docusaurus handles versioning with one CLI command, which Starlight does not offer.

How much did field INP change after moving to Starlight?

The 75th-percentile INP from real-user monitoring fell from 210 ms on Docusaurus to 96 ms on Starlight over comparable four-week windows, because the pages stopped hydrating a full React tree.

Can Starlight use React components from our design system?

Yes. Add the Astro React integration and render components with a client directive only where they need interactivity. Static components render to HTML with no JavaScript shipped.