---
title: "From Starlight"
description: "Migrate Starlight Astro content, sidebar groups, frontmatter, expressive code, and components"
canonical_url: "https://docs.farming-labs.dev/docs/migrations/starlight"
markdown_url: "https://docs.farming-labs.dev/docs/migrations/starlight.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 1550
  task: "Migrate an Astro Starlight site into Farming Labs Docs."
  outcome: "Starlight content, sidebar order, frontmatter, and supported Markdown render through the Farming Labs Astro adapter or another selected runtime."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "Preserve astro.config, src/content/docs, public assets, Starlight components, overrides, plugins, and locale settings."
    - "Record the docs base path and generated sidebar behavior."
    - "Initialize the target runtime in a migration branch."
  files:
    - "astro.config.mjs"
    - "astro.config.ts"
    - "src/content.config.ts"
    - "src/content/config.ts"
    - "src/lib/docs.config.ts"
  commands:
    - run: "npx @farming-labs/docs init"
      description: "Scaffold Farming Labs Docs in the target application."
  sideEffects:
    - "Starlight integration configuration, sidebar data, and component overrides are translated into Farming Labs and application configuration."
  verification:
    - description: "Build the target and compare routes, autogeneration, frontmatter, expressive code, components, locales, and assets."
      expect: "The production build passes and each required source page remains reachable."
  rollback:
    - "Restore the Starlight integration and original content collection from the migration branch."
  failureModes:
    - symptom: "Sidebar items disappear after copying files."
      resolution: "Translate manual sidebar entries and autogenerated directory roots separately, then add explicit page order."
    - symptom: "A Starlight component import fails."
      resolution: "Replace it with a Farming Labs component or a component native to the selected target runtime."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Migrate an Astro Starlight site into Farming Labs Docs.
Outcome: Starlight content, sidebar order, frontmatter, and supported Markdown render through the Farming Labs Astro adapter or another selected runtime.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- Preserve astro.config, src/content/docs, public assets, Starlight components, overrides, plugins, and locale settings.
- Record the docs base path and generated sidebar behavior.
- Initialize the target runtime in a migration branch.

### Files

- `astro.config.mjs`
- `astro.config.ts`
- `src/content.config.ts`
- `src/content/config.ts`
- `src/lib/docs.config.ts`

### Commands

- `npx @farming-labs/docs init` — Scaffold Farming Labs Docs in the target application.

### Side Effects

- Starlight integration configuration, sidebar data, and component overrides are translated into Farming Labs and application configuration.

### Verification

- Build the target and compare routes, autogeneration, frontmatter, expressive code, components, locales, and assets.
  - Expected: The production build passes and each required source page remains reachable.

### Rollback

- Restore the Starlight integration and original content collection from the migration branch.

### Failure Modes

- Sidebar items disappear after copying files. — Recovery: Translate manual sidebar entries and autogenerated directory roots separately, then add explicit page order.
- A Starlight component import fails. — Recovery: Replace it with a Farming Labs component or a component native to the selected target runtime.
<!-- farming-labs:agent-contract:end -->

# From Starlight

## From Starlight task

Task: Migrate an Astro Starlight site into Farming Labs Docs.

Expected result: Starlight content, sidebar order, frontmatter, and supported Markdown render through the Farming Labs Astro adapter or another selected runtime.

## From Starlight prerequisites

- Preserve astro.config, src/content/docs, public assets, Starlight components, overrides, plugins, and locale settings.
- Record the docs base path and generated sidebar behavior.
- Initialize the target runtime in a migration branch.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From Starlight verification

- Build the target and compare routes, autogeneration, frontmatter, expressive code, components, locales, and assets. Expected: The production build passes and each required source page remains reachable.
- Failure: Sidebar items disappear after copying files.
- Recovery: Translate manual sidebar entries and autogenerated directory roots separately, then add explicit page order.
- Rollback: Restore the Starlight integration and original content collection from the migration branch.

## From Starlight agent guidance

Read the starlight() integration options in astro.config and resolve every sidebar item, autogenerate
directory, locale, plugin, and component override. Do not copy Starlight config keys into
docs.config without mapping their behavior.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).