Migrate Docusaurus to Astro Starlight

Why Move From Docusaurus to Astro Starlight

Docusaurus has served the React documentation ecosystem well. Teams could spin up docs sites with versioning, search, and MDX support pretty quickly. But it ships a full React runtime to every visitor, and that weight shows up in every Lighthouse audit.

Astro Starlight is built specifically for documentation. It renders static HTML by default, ships zero JavaScript unless you explicitly opt in, and includes built-in search, sidebar navigation, and i18n out of the box. Your MDX files transfer directly. Astro's own team keeps the migration path well-documented.

If your Docusaurus site feels sluggish on mobile, if build times keep creeping up as your docs grow, or if you're tired of fighting React hydration issues on what should be static content — Starlight fixes all of that.

The Real Problems With Docusaurus at Scale

Client-Side JavaScript Overhead

Docusaurus ships React to the browser. Every page load includes the React runtime, React DOM, and the client-side routing layer. For a documentation site where 99% of pages are static text and code blocks, this is dead weight. Mobile Lighthouse scores typically land between 45-65 because of it.

Build Performance Degradation

As your doc collection grows past a few hundred pages, Docusaurus builds slow down noticeably. Webpack bundling makes it worse. Teams with 500+ doc pages report build times exceeding 5 minutes, which kills CI/CD feedback loops.

Plugin Ecosystem Lock-In

Docusaurus plugins are tightly coupled to its internal architecture. Need custom remark plugins? They work, but the configuration layer adds complexity. Want to swap the search provider? You're working within Docusaurus's preset system, which constrains what's possible.

Sidebar Configuration Rigidity

Docusaurus sidebar configs use a specific JSON/JS schema with category, items, and type fields. It works, but the configuration grows unwieldy for large doc trees with deep nesting. Reordering sections means editing config files rather than just moving files around.

React Component Dependencies

Custom components in Docusaurus are React components that hydrate on the client. If you've built interactive examples, tabbed content, or custom admonitions, they all carry the React hydration cost — even when the interactivity is minimal.

What Astro Starlight Gives You

Zero-JS by Default

Starlight generates pure static HTML and CSS. No framework runtime ships to the browser unless you explicitly add an interactive island. Documentation pages load in under 200ms on 3G connections. Lighthouse scores hit 95-100 consistently.

MDX Compatibility

Starlight includes Astro's MDX integration by default. Your existing .mdx files work immediately. Frontmatter fields map cleanly — title, description, sidebar_label all have Starlight equivalents. Remark and rehype plugins carry over without changes.

Built-In Pagefind Search

Starlight ships with Pagefind, a static search engine that indexes your built HTML and runs entirely in the browser. No external service, no API keys, no Algolia crawl delays. Search works offline and adds roughly 10KB to your bundle. For teams that specifically need Algolia, there's an official Starlight plugin for DocSearch.

File-Based Sidebar Generation

Starlight can auto-generate sidebars from your file structure. Drop an MDX file in a folder, it shows up in the sidebar. You can still override with explicit configuration, but the default behavior eliminates most sidebar config maintenance.

Content Collections with Type Safety

Starlight uses Astro's content collections, which validate your frontmatter against a Zod schema at build time. Typos in frontmatter fields get caught before deployment, not discovered by users.

Our Migration Process

Phase 1: Audit and Planning

We start by inventorying your Docusaurus site — page count, custom components, plugin usage, sidebar structure, versioning setup, and any custom themes. We map every Docusaurus feature to its Starlight equivalent and flag gaps that need custom solutions.

Phase 2: Starlight Scaffolding

We spin up a new Starlight project using yarn create astro --template starlight and configure it to match your existing site's structure. We set up content collections, configure the astro.config.mjs, and establish the folder hierarchy that mirrors your current URL structure.

Phase 3: Content Migration

MDX files transfer with minimal changes. We handle:

• Frontmatter remapping: Docusaurus-specific fields like sidebar_position, sidebar_label, and slug get converted to Starlight's frontmatter schema
• Import statement updates: Component imports change from Docusaurus paths to Astro component paths
• Admonition syntax: Docusaurus uses :::note syntax; Starlight uses <Aside> components or its own admonition syntax
• Tab components: <Tabs> and <TabItem> from Docusaurus get replaced with Starlight's built-in tab components

Phase 4: Sidebar Config Remapping

Docusaurus sidebar configs using category/items patterns get converted to Starlight's sidebar configuration format. Where possible, we switch to auto-generated sidebars driven by file structure, reducing config maintenance to zero.

// Docusaurus sidebars.js
module.exports = {
  docs: [
    { type: 'category', label: 'Getting Started', items: ['intro', 'installation'] },
  ],
};

// Starlight astro.config.mjs
starlight({
  sidebar: [
    { label: 'Getting Started', autogenerate: { directory: 'getting-started' } },
  ],
})

Phase 5: Plugin and Integration Mapping

We replace Docusaurus plugins with Astro integrations:

• @docusaurus/plugin-google-gtag → Astro's @astrojs/partytown with inline gtag
• @docusaurus/plugin-sitemap → @astrojs/sitemap
• Algolia DocSearch → Pagefind (built-in) or starlight-docsearch plugin
• @docusaurus/plugin-client-redirects → Astro redirects in config or astro-redirect
• Custom remark/rehype plugins → Direct transfer, same plugin ecosystem

Phase 6: Search Migration

If you're on Algolia DocSearch, we migrate to Pagefind by default. Pagefind indexes at build time, requires no external service, and delivers instant search with fuzzy matching. If your team specifically needs Algolia — for analytics or AI-powered answers — we configure the official starlight-algolia plugin instead.

Phase 7: QA and Launch

We run a full crawl comparison between old and new sites, verify every URL resolves, test search functionality, validate mobile rendering, and confirm Lighthouse scores meet our targets.

SEO Preservation Strategy

Documentation sites accumulate significant search authority. We protect every bit of it:

• URL parity: We match your existing URL structure exactly. If Docusaurus served /docs/getting-started, Starlight serves the same path
• 301 redirects: For any URLs that must change, we configure server-level redirects on Vercel or Cloudflare
• Canonical tags: Every page gets a proper canonical URL
• Sitemap generation: @astrojs/sitemap produces an updated sitemap submitted to Search Console
• Meta preservation: Title tags, meta descriptions, and Open Graph tags transfer from existing frontmatter
• Structured data: We add documentation-specific JSON-LD where applicable

Timeline and Pricing

Most Docusaurus to Starlight migrations complete in 1-3 weeks depending on site complexity:

• Small sites (under 50 pages, minimal custom components): 1 week, starting at $3,000
• Medium sites (50-200 pages, custom components, versioning): 2 weeks, starting at $6,000
• Large sites (200+ pages, heavy customization, multiple locales): 3+ weeks, starting at $10,000

Every project begins with a free migration audit where we assess your specific Docusaurus setup and provide an exact scope and timeline.