---
url: /en/docs/frameworks/docusaurus.md
description: >-
  Learn how to integrate Sveltia CMS with Docusaurus, including the admin page
  setup, blog and docs collection configuration and real-world examples.
---

# Docusaurus Integration Guide

This guide provides resources and information for integrating Sveltia CMS with [Docusaurus](https://docusaurus.io/), a popular static site generator focused on documentation websites.

## Examples

See real-world examples of Docusaurus integrations in our [Showcase](/en/showcase?framework=docusaurus). 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](https://docusaurus.io/docs/static-assets). Create `static/admin/index.html` and `static/admin/config.yml` as described in the [Getting Started](/en/docs/start#manual-installation) 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](https://docusaurus.io/docs/advanced/routing#escaping-from-spa-redirects) to link to it as if it were an external page:

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

## Configuration

### Blog Posts

The [blog plugin](https://docusaurus.io/docs/blog) 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](/en/docs/media/internal#using-entry-relative-folders), so images inserted into a post are stored next to its `index.md` file:

```yaml [static/admin/config.yml]
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](https://docusaurus.io/docs/blog#blog-post-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](https://docusaurus.io/docs/blog#blog-post-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](https://docusaurus.io/docs/create-doc), and the folder structure becomes the sidebar structure. A [nested collection](/en/docs/collections/entries/nested) with the `subfolders: false` mode manages this structure as a folder tree:

```yaml
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](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter) options that control the [autogenerated sidebar](https://docusaurus.io/docs/sidebar/autogenerated). 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`](/en/docs/data-output#controlling-data-output) output option to `true` to leave them out:

```yaml
output:
  omit_empty_optional_fields: true
```

::: warning MDX Content

Docusaurus parses `.md` and `.mdx` files as [MDX](https://docusaurus.io/docs/markdown-features/react) by default, which allows JSX components in Markdown. Sveltia CMS doesn’t support MDX yet (it’s on our [roadmap](/en/docs/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`](/en/docs/collections/entries/formats#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](/en/docs/collections/entries/slugs#entry-slugs) and [summary](/en/docs/collections/entries/listings#summaries) of the entries will be generated from a header in the Markdown content, if exists. ([Discussion](https://github.com/sveltia/sveltia-cms/issues/230))
* [Nested collections](/en/docs/collections/entries/nested): Manage a [docs folder tree](https://docusaurus.io/docs/create-doc) 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.