Starlight Integration Guide

This guide provides resources and information for integrating Sveltia CMS with Starlight, a documentation website framework built on Astro.

Setup

Adding the Admin Page

Like any Astro site, Starlight serves static files from the public folder. Create public/admin/index.html and public/admin/config.yml as described in the Getting Started 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, the sidebar structure. A nested collection with the subfolders: false mode manages this structure as a folder tree, where editors can create new folders as needed:

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 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() 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 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, such as en and fr. This matches the multiple_folders i18n structure of Sveltia CMS:

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 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, 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 option to match this structure:

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.