Docusaurus Integration Guide

This guide provides resources and information for integrating Sveltia CMS with Docusaurus, a popular static site generator focused on documentation websites.

Examples

See real-world examples of Docusaurus integrations in our Showcase. Most of the listed sites include links to their source code, so you can explore how they implemented Sveltia CMS with Docusaurus.

Setup

Adding the Admin Page

Docusaurus serves static files from the static folder. Create static/admin/index.html and static/admin/config.yml as described in the Getting Started guide. The admin page is then available at /admin/ on the development server started with docusaurus start as well as on the built site.

Linking to the Admin Page

The admin page is not part of the Docusaurus route system, so a regular link to it would be handled by the client-side router and lead to a 404 page. Use the pathname:// protocol to link to it as if it were an external page:

[Edit content](pathname:///admin/)

Configuration

Blog Posts

The blog plugin reads posts from the blog folder and takes the date and slug from date-prefixed names. A post can be a single file like 2026-10-01-hello-world.md, or a folder like 2026-10-01-hello-world/index.md that also holds the post’s images. The following example uses the folder style with entry-relative media folders, so images inserted into a post are stored next to its index.md file:

media_folder: static/img
public_folder: /img
collections:
  - name: blog
    label: Blog
    folder: blog
    path: '{{year}}-{{month}}-{{day}}-{{slug}}/index'
    media_folder: ''
    public_folder: ''
    create: true
    fields:
      - { name: title, label: Title }
      - { name: description, label: Description, required: false }
      - name: authors
        label: Authors
        widget: list
        required: false
        fields:
          - { name: name, label: Name }
          - { name: title, label: Title, required: false }
          - { name: url, label: URL, required: false }
          - { name: image_url, label: Image URL, required: false }
      - { name: tags, label: Tags, widget: list, required: false }
      - { name: draft, label: Draft, widget: boolean, required: false }
      - { name: body, label: Body, widget: markdown }

Some notes on authors and tags:

• Authors are defined inline in the example above. If you maintain the authors in blog/authors.yml instead, the front matter refers to them by key, such as authors: [jane]. Since the file is a map keyed by author, it can’t be edited easily in the CMS, but a Select field with the keys as options and multiple: true lets editors pick authors from the list.
• Tags can be free-form strings, as in the example above. If you predefine tags in blog/tags.yml, Docusaurus warns about tags that are not in the file by default, so use a Select field with the same keys as options and multiple: true instead of a List field.

Docs

Every Markdown file in the docs folder becomes a doc page, and the folder structure becomes the sidebar structure. A nested collection with the subfolders: false mode manages this structure as a folder tree:

collections:
  - name: docs
    label: Docs
    label_singular: Doc
    folder: docs
    create: true
    nested:
      subfolders: false
    meta: { path: {} }
    fields:
      - { name: title, label: Title }
      - { name: sidebar_label, label: Sidebar Label, required: false }
      - { name: sidebar_position, label: Sidebar Position, widget: number, required: false }
      - { name: body, label: Body, widget: markdown }

The sidebar_label and sidebar_position fields correspond to the front matter options that control the autogenerated sidebar. Category labels and positions are defined in _category_.json or _category_.yml files, which are not entries and can be edited outside the CMS.

Docusaurus validates front matter and stops the build when an optional property has an empty value, such as sidebar_position: null or sidebar_label: ''. Since Sveltia CMS saves empty values for optional fields by default, set the omit_empty_optional_fields output option to true to leave them out:

output:
  omit_empty_optional_fields: true

MDX Content

Docusaurus parses .md and .mdx files as MDX by default, which allows JSX components in Markdown. Sveltia CMS doesn’t support MDX yet (it’s on our roadmap), so editing a file with components in the rich text editor may change or break them. Also, an entry collection uses one file extension, so .md and .mdx files in the same folder need to be managed by separate collections with the extension option.

Support for Docusaurus

We have implemented specific features to enhance the integration of Sveltia CMS with Docusaurus:

• If an entry collection has only a Markdown body field, the slug and summary of the entries will be generated from a header in the Markdown content, if exists. (Discussion)
• Nested collections: Manage a docs folder tree in the sidebar with the subfolders: false mode, where every file is a page at its own path and editors can create new folders as needed.