---
url: /en/docs/frameworks/starlight.md
description: >-
  Learn how to integrate Sveltia CMS with Starlight, the Astro documentation
  theme, including the admin page setup, docs collection configuration and
  multilingual content.
---

# Starlight Integration Guide

This guide provides resources and information for integrating Sveltia CMS with [Starlight](https://starlight.astro.build/), a documentation website framework built on [Astro](/en/docs/frameworks/astro).

## Setup

### Adding the Admin Page

Like any Astro site, Starlight serves static files from the [`public` folder](https://starlight.astro.build/guides/project-structure/). Create `public/admin/index.html` and `public/admin/config.yml` as described in the [Getting Started](/en/docs/start#manual-installation) guide.

The Astro development server doesn’t serve `index.html` for a folder path in `public`, so open `/admin/index.html` instead of `/admin/` during development. On the built site, most hosting services serve the admin page at `/admin/` as usual.

## Configuration

### Docs Collection

Starlight turns every Markdown file in `src/content/docs` into a page at its own path, and the folder structure becomes the URL structure and, with [autogenerated sidebar groups](https://starlight.astro.build/guides/sidebar/#autogenerated-links), the sidebar structure. A [nested collection](/en/docs/collections/entries/nested) with the `subfolders: false` mode manages this structure as a folder tree, where editors can create new folders as needed:

```yaml [public/admin/config.yml]
media_folder: public/images
public_folder: /images
output:
  omit_empty_optional_fields: true
collections:
  - name: docs
    label: Docs
    label_singular: Page
    folder: src/content/docs
    create: true
    nested:
      subfolders: false
    meta: { path: {} }
    fields:
      - { name: title, label: Title }
      - { name: description, label: Description, required: false }
      - name: sidebar
        label: Sidebar
        widget: object
        required: false
        collapsed: true
        fields:
          - { name: label, label: Label, required: false }
          - { name: order, label: Order, widget: number, required: false }
          - { name: hidden, label: Hidden, widget: boolean, required: false }
          - { name: badge, label: Badge, required: false }
      - name: template
        label: Template
        widget: select
        options: [doc, splash]
        default: doc
      - { name: draft, label: Draft, widget: boolean, required: false }
      - { name: body, label: Body, widget: markdown }
```

The fields correspond to the [front matter](https://starlight.astro.build/reference/frontmatter/) options of the same names. `title` is the only required option in Starlight. Add other options, such as `hero` for a splash page or `tableOfContents`, as needed.

### Omitting Empty Optional Fields

Starlight validates front matter with the [`docsSchema()`](https://starlight.astro.build/reference/configuration/#docsschema) helper defined in `src/content.config.ts`. The schema uses Zod’s `.optional()`, which only accepts a missing property, so an empty value saved by Sveltia CMS for an optional field, such as `order: null`, can cause a build error. The [`omit_empty_optional_fields`](/en/docs/data-output#controlling-data-output) output option in the example above leaves such fields out of the front matter.

### Images

Images uploaded in the CMS are saved in the `public/images` folder in the example above and referenced as `/images/file.png`. Starlight serves these files as is. If you want Astro to optimize images, they need to be stored in `src/assets` or next to the page and referenced with a relative path, which is not supported by the `subfolders: false` mode because the relative path differs for each folder level.

## Multilingual Sites

Starlight stores the pages of each language in a subfolder of `src/content/docs` named after the [locale](https://starlight.astro.build/guides/i18n/), such as `en` and `fr`. This matches the [`multiple_folders`](/en/docs/i18n/structures) i18n structure of Sveltia CMS:

```yaml [public/admin/config.yml]
i18n:
  structure: multiple_folders
  locales: [en, fr]
collections:
  - name: docs
    # ...
    i18n: true
    fields:
      - { name: title, label: Title, i18n: true }
      - { name: description, label: Description, required: false, i18n: true }
      # ...
      - { name: body, label: Body, widget: markdown, i18n: true }
```

Each locale has its own file, so fields that should appear in every file need the field-level [`i18n`](/en/docs/i18n/options#field-level-configuration) option. Set it to `true` for translatable fields like `title`, which Starlight requires for every page, and `duplicate` for fields that should have the same value in all locales, such as the sidebar order.

If your site uses a [root locale](https://starlight.astro.build/guides/i18n/#use-a-root-locale), the pages of the default language are stored directly in `src/content/docs`, while the other languages are in their own subfolders. Add the [`omit_default_locale_from_file_path`](/en/docs/i18n/options#top-level-configuration) option to match this structure:

```yaml [public/admin/config.yml]
i18n:
  structure: multiple_folders
  locales: [en, fr]
  omit_default_locale_from_file_path: true
```

With this option, a folder in the default language whose name matches another locale code, such as `fr`, is treated as that locale’s folder, so avoid using locale codes as folder names.