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

# VitePress Integration Guide

This guide provides resources and information for integrating Sveltia CMS with [VitePress](https://vitepress.dev/), a static site generator powered by Vite and Vue.

## Examples

See real-world examples of VitePress integrations in our [Showcase](/en/showcase?framework=vitepress). 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](https://vitepress.dev/guide/asset-handling#the-public-directory) 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](/en/docs/start#manual-installation) 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](https://vitepress.dev/guide/routing#linking-to-non-vitepress-pages) so they are opened as regular pages:

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

The same applies to a link in the [navigation bar](https://vitepress.dev/reference/default-theme-nav#navigation-links):

```js [.vitepress/config.js]
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](/en/docs/collections/entries/nested) with the `subfolders: false` mode manages this structure as a folder tree. The following example manages all the pages in the `docs` folder:

```yaml [docs/public/admin/config.yml]
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](https://vitepress.dev/reference/frontmatter-config) options of the same names, and `layout` selects one of the [default theme layouts](https://vitepress.dev/reference/default-theme-layout). 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](/en/docs/collections/files) of its own instead.

## Support for VitePress

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

* The [`folder` option](/en/docs/collections/entries#creating-an-entry-collection) for an entry collection can be an empty string (or `.` or `/`) if you want to store entries in the root folder. ([Discussion](https://github.com/sveltia/sveltia-cms/issues/230))
* 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 [folder tree of pages](https://vitepress.dev/guide/routing#source-directory) 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.