CMS Configuration (config.yml)

Sveltia CMS operates as a lightweight, headless visual editor that commits directly to your Git repository. It doesn’t require a database; instead, it relies on a single config.yml file located in the public directory (public/admin/config.yml).

This file is the bridge. It defines every collection, folder path, and form field available to authors, ensuring the visual CMS maps perfectly to the Zod schemas defined in our Astro backend (src/content.config.ts).

The Configuration Architecture

Explore the directory setup and the underlying YAML configuration that powers the CMS admin panel.

Where the CMS entry point lives in your project.

public/
  admin/
    index.html      # Loads the Sveltia CMS SPA script
    config.yml      # Defines collections, fields, and Git backend

Mapping Markdown collections and frontmatter fields.

backend:
  name: github
  repo: write-tim/docs-as-code
  branch: main

media_folder: src/assets
public_folder: /src/assets

collections:
  - name: guides
    label: Architecture Guides
    folder: src/content/docs/guides
    create: true
    fields:
      - { name: title, label: Title, widget: string }
      - { name: description, label: Description, widget: string, required: false }
      - { name: sidebar.order, label: Sidebar Order, widget: number, required: false }
      - { name: body, label: Body, widget: markdown }

  - name: components
    label: Component Library
    folder: src/content/docs/components
    create: true
    fields:
      - { name: title, label: Title, widget: string }
      - { name: description, label: Description, widget: string, required: false }
      - { name: sidebar.order, label: Sidebar Order, widget: number, required: false }
      - { name: body, label: Body, widget: markdown }

How It Works Under the Hood

The Backend: Lines 2-5 tell Sveltia to use GitHub OAuth to authenticate users and specify which repository and branch (main) will receive the commits.
The Folder Mapping: The folder declarations route specific content types to their proper directories (e.g., routing the Architecture Guides collection specifically to src/content/docs/guides).
The Frontmatter Fields: The fields arrays define the visual input fields for authors. If an author types a title into the CMS, Sveltia formats it into the title: YAML frontmatter of the compiled .mdx file.

Field Types & Customization

Sveltia CMS supports a wide array of form widgets that make content authoring intuitive for non-technical users:

string: Used for single-line text fields like article titles and meta descriptions.
number: Used for integers, such as defining the sidebar.order to control navigation hierarchy.
markdown: Renders a full rich-text editor (supporting bold, lists, links, and code blocks) while maintaining clean underlying Markdown syntax.
image: Uploads media assets directly into the src/assets folder, allowing Astro to automatically optimize images during build time.