Lotus
Type to search documentation.

Migrations

Starlight

Move existing Starlight content into Lotus with compatible frontmatter and MDX patterns.

View as MarkdownOpen in ChatGPTOpen in Claude

Use this migration when an existing Astro Starlight site already has docs content, localized directories, sidebar configuration, and Starlight MDX components.

Lotus keeps several authoring patterns close to Starlight: frontmatter fields, Steps, FileTree, localized directories, and sidebar-style content organization. The main migration work is moving configuration into Lotus and replacing Starlight-specific component imports.

  1. Move content into the Lotus docs collection.

    Register docsLoader() and docsSchema() in src/content.config.ts.

  2. Keep compatible frontmatter.

    Fields such as title, description, slug, sidebar, tableOfContents, prev, next, pagefind, and draft are accepted.

  3. Rebuild sidebars in theme.config.ts.

    Lotus owns sidebar structure from themeConfig.sidebars. Use string items, groups, links, and autogenerate.directory entries.

  4. Replace Starlight-only components.

    Use @prosefly/astro-components for Steps, FileTree, Tabs, cards, callouts, accordions, badges, and icons.

  5. Configure i18n explicitly.

    Use locales and defaultLocale to map locale directories to public route prefixes.

See Frontmatter for accepted page fields and Sidebars for navigation structure.

AI-assisted Migration Prompt

Use this prompt with Codex or another code-aware AI assistant when you want it to migrate an existing Starlight project automatically. Run it from the project root so the assistant can inspect package.json, Astro config, content collections, docs files, and theme configuration.

Prompt
You are migrating an existing Astro Starlight documentation site to
@prosefly/astro-theme-lotus.


Goal:
Move the project from Starlight to Lotus while preserving existing documentation
content, routes, frontmatter intent, sidebars, i18n structure, search behavior,
and MDX authoring patterns wherever Lotus supports them.


Before editing:
1. Inspect package.json, astro.config.*, src/content.config.*, docs content,
   sidebar configuration, i18n directories, Starlight component imports, and any
   custom theme overrides.
2. Summarize the migration plan briefly.
3. Do not delete content or rewrite prose unless it is required for compatibility.
4. Preserve user changes and avoid destructive git commands.


Migration tasks:
1. Replace Starlight package usage with @prosefly/astro-theme-lotus and
   @prosefly/astro-components where appropriate.
2. Update Astro integration setup to use Lotus.
3. Register docsLoader() and docsSchema() in src/content.config.ts.
4. Move Starlight site, sidebar, social, edit link, i18n, search, and appearance
   settings into src/theme.config.ts using defineLotusConfig().
5. Preserve compatible frontmatter fields including title, description, slug,
   sidebar, tableOfContents, prev, next, pagefind, and draft.
6. Convert Starlight-only MDX component imports to @prosefly/astro-components.
   Prefer Lotus-compatible components for Callout, Steps, FileTree, Tabs, cards,
   accordions, badges, and icons.
7. Convert Starlight sidebar autogeneration to Lotus sidebars[].items entries
   using string slugs, groups, links, and autogenerate.directory.
8. Convert Starlight locales into Lotus locales and defaultLocale. Keep root
   locale unprefixed when the existing site uses unprefixed default docs.
9. Keep docsBase and route behavior compatible with the existing public URLs
   whenever possible.
10. If the project has custom Starlight components or theme overrides, map them
    to Lotus configuration, CSS tokens, or component overrides. Only add a Lotus
    component override when configuration and CSS are not enough.


Validation:
1. Run the project's formatter or lint command if available.
2. Run astro check or the package check command.
3. Run a production build.
4. Report any remaining Starlight imports, broken internal /docs links, missing
   sidebar entries, or behavior that needs manual review.


Output:
1. List the files changed.
2. Explain any manual decisions or behavior changes.
3. Include the exact validation commands and results.

After the AI finishes, compare its changes with the Lotus pages for Content Routing, Internationalization, Sidebars, and Overriding Components.

Last updated Jul 18, 2026

Contributors