Migrate from StarlightCopy Anchor Link

Starlight stores documentation in Astro content collections and uses standard Markdown or MDX, so the Astro-to-Astro path is especially direct. The key work is translating sidebar configuration, Starlight components, expressive code options, and integration behavior.

1. Inventory the sourceCopy Anchor Link

Collect:

• astro.config.* and the starlight(...) integration
• src/content/docs/ Markdown and MDX
• src/content.config.* or src/content/config.*
• manual and autogenerated sidebar definitions
• src/components/ and Starlight component overrides
• src/styles/, public/, logos, favicons, and social images
• plugins, expressive code config, locales, redirects, search, and custom head tags

2. Map the filesCopy Anchor Link

Keep the existing Astro application when it contains non-doc routes; replace only the Starlight docs integration and route surface.

3. Preserve routes and frontmatterCopy Anchor Link

Starlight normally derives docs routes from files under src/content/docs. Preserve directory and filename slugs, then review:

• title
• description
• slug
• sidebar
• tableOfContents
• template
• hero
• banner
• edit and pagination settings

Portable title and description fields can remain. Translate layout, hero, banner, and sidebar objects into Farming Labs page content, theme configuration, or application UI.

4. Translate sidebar configurationCopy Anchor Link

Starlight supports link items, groups, badges, translations, and autogenerated directories.

1. Snapshot the fully resolved sidebar.
2. Turn groups into directories with landing pages when useful.
3. Add numeric order values matching manual item order.
4. Expand autogenerated directories into their actual page list.
5. Preserve external links through custom navigation.
6. Recreate labels and badges with stable text and registered icons.

Do not lose pages excluded from autogeneration; classify them as hidden, redirected, or retired.

5. Convert authoring featuresCopy Anchor Link

Standard Markdown, headings, tables, links, and fenced code should remain unchanged.

6. Replace integration behaviorCopy Anchor Link

Map Starlight integration options intentionally:

• metadata and social images → metadata and og
• search → search
• edit links and page actions → github and pageActions
• locales → Farming Labs locale configuration
• custom CSS → theme overrides and global CSS
• component overrides → theme config or registered components
• plugins → built-in feature config or a separate Astro integration

7. Validate and recoverCopy Anchor Link

1. Run the Astro production build.
2. Compare all src/content/docs routes and manual sidebar links.
3. Test autogenerated groups, badges, callouts, tabs, cards, and expressive code.
4. Inspect locale navigation and base paths.
5. Verify assets and application routes outside docs.
6. Fetch representative pages through .md.

If navigation is incomplete, compare the resolved Starlight sidebar with the target tree. If an Astro component fails after changing runtime, replace it with portable Markdown or a native target component.

Source referencesCopy Anchor Link

• Starlight sidebar configuration
• Starlight authoring
• Starlight components
• Farming Labs sidebar
• Farming Labs configuration