VitePress Integration Guide

This guide provides resources and information for integrating Sveltia CMS with VitePress, a static site generator powered by Vite and Vue.

Examples

See real-world examples of VitePress 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 VitePress.

Setup

Adding the Admin Page

VitePress serves static files from the public folder inside the source folder, which is the project root by default but is often a subfolder named docs. For example, if your Markdown files are in docs, create docs/public/admin/index.html and docs/public/admin/config.yml as described in the Getting Started guide.

The VitePress development server doesn’t serve index.html for a folder path, 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.

Linking to the Admin Page

VitePress handles internal links with its client-side router, which shows a 404 page for the admin page because it isn’t a VitePress page. Add target="_self" to links to non-VitePress pages so they are opened as regular pages:

[Edit content](/admin/){target="_self"}

The same applies to a link in the navigation bar:

export default {
  themeConfig: {
    nav: [{ text: 'Edit', link: '/admin/', target: '_self' }],
  },
};

Configuration

In VitePress, every Markdown file in the source folder becomes a page at its own path, and the folder structure becomes the URL structure. A nested collection with the subfolders: false mode manages this structure as a folder tree. The following example manages all the pages in the docs folder:

media_folder: docs/public/images
public_folder: /images
collections:
  - name: pages
    label: Pages
    label_singular: Page
    folder: docs
    create: true
    nested:
      subfolders: false
    meta: { path: {} }
    fields:
      - { name: title, label: Title }
      - { name: description, label: Description, required: false }
      - name: layout
        label: Layout
        widget: select
        options: [doc, home, page]
        default: doc
      - { name: body, label: Body, widget: markdown }

The title and description fields correspond to the front matter options of the same names, and layout selects one of the default theme layouts. VitePress can take the page title from the first heading instead, but the title field is required here because Sveltia CMS uses it to generate the file name of a new page. The home page uses many layout-specific options, such as hero and features, so you may want to manage index.md with a file collection of its own instead.

Support for VitePress

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

• The folder option for an entry collection can be an empty string (or . or /) if you want to store entries in the root folder. (Discussion)
• 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 folder tree of pages 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.