VitePress Patterns

Quick Guide: VitePress is a Vue-powered static site generator for documentation, configured entirely in .vitepress/config.ts. The sidebar is either an array (one sidebar everywhere) or an object keyed by URL path prefix (a sidebar per section). Data loaders — files ending .data.ts — run at build time and ship only their serialized result to the client. Vue components work directly inside Markdown through <script setup>. Every page is pre-rendered at build time, which is the constraint behind most of the red flags below.

>

Version: VitePress 1.6.x, on Vite 6+ and Vue 3.5+.

Detailed Resources:

• examples/core.md — full config, multi-sidebar, content and custom data loaders, theme extension and CSS variables, Vue in Markdown, markdown extensions, build hooks, home page, i18n, markdown-it plugins, dynamic routes, rewrites, deployment
• reference.md — CLI commands, site and theme config tables, frontmatter fields, runtime API, CSS variable categories, layout slots, markdown syntax

<critical_requirements>

Before writing VitePress code

Put site configuration in `.vitepress/config.ts` and wrap it in `defineConfig()`. That path is where the build looks, and the wrapper is what gives the option names type checking.

*Load data through a `.data.ts` loader rather than fetching in a component.** The loader runs at build time and the client receives only the serialized result, which is both faster and SSR-safe.

Guard browser APIs with `<ClientOnly>` or `onMounted`. Every page is pre-rendered at build time, so a bare window or document reference crashes the build rather than the browser.

Extend the default theme with `extends: DefaultTheme` plus layout slots. A fork is a copy that stops tracking upstream, and the slot list is broad enough that forking is rarely the shorter route.

Build Markdown collection pages with `createContentLoader()`. It already handles the glob, the frontmatter extraction, mtime caching and dev-mode watching.

</critical_requirements>

Auto-detection: VitePress, vitepress, .vitepress/config, defineConfig vitepress, createContentLoader, vitepress/theme, DefaultTheme, useData, useSidebar, markdown-it plugin vitepress, vitepress deploy

Applies to:

• Site and theme configuration in .vitepress/config.ts
• Navigation: nav bar, single and multi-sidebar, outline, edit links
• Data loaders — createContentLoader for Markdown collections, custom load() for anything else
• Vue components in Markdown, page-scoped and globally registered
• Theme extension through layout slots, custom layouts and CSS variables
• Markdown extensions: containers, code groups, line highlighting and annotations, snippets, includes
• Build hooks: transformPageData, transformHead, transformHtml, buildEnd
• markdown-it plugin integration, dynamic routes, URL rewrites, i18n, deployment

Handled elsewhere:

• Vue component authoring itself — this skill covers where a component may go and what the SSR boundary demands of it, not the component model.
• Request-time behaviour — the build emits static files, so anything needing a server at request time lives outside the site.
• Content from a CMS or database at request time; a loader can read one at build time, which is a different thing.
• Design decisions behind the CSS variables — those variables are the seam, and what you set them to is not this skill's call.
• API reference generated from a machine-readable spec — that generation is upstream of the Markdown VitePress reads.

<patterns>

Core patterns

Pattern 1: Site configuration

One file, wrapped for type checking. cleanUrls drops .html from URLs, sitemap.hostname generates sitemap.xml, lastUpdated reads git timestamps, and search.provider: "local" is search with no service to sign up for.

import { defineConfig } from "vitepress";

export default defineConfig({
  title: "My Docs",
  cleanUrls: true,
  lastUpdated: true,
  sitemap: { hostname: "https://docs.example.com" },
  themeConfig: {
    nav: [{ text: "Guide", link: "/guide/" }],
    sidebar: {
      /* Pattern 2 */
    },
    search: { provider: "local" },
    editLink: { pattern: "https://github.com/org/repo/edit/main/docs/:path" },
  },
});

Full code: examples/core.md

Pattern 2: Multi-sidebar

An array gives one sidebar for the whole site. An object keyed by path prefix gives a different sidebar per section, and the first matching prefix wins.

sidebar: {
  "/guide/": [
    { text: "Getting Started", collapsed: false, items: [{ text: "Introduction", link: "/guide/introduction" }] },
    { text: "Advanced", collapsed: true, items: [{ text: "Data Loaders", link: "/guide/data-loading" }] },
  ],
  "/api/": [{ text: "API Reference", items: [{ text: "Config", link: "/api/config" }] }],
}

The trailing slash matters: /guide also matches /guidelines. Omitting collapsed makes a group permanently expanded rather than collapsible.

Full code: examples/core.md

Pattern 3: Data loaders

A *.data.ts file runs at build time and exports data. createContentLoader covers Markdown collections; a plain object with watch and load() covers everything else.

// posts.data.ts
import { createContentLoader } from "vitepress";

export default createContentLoader("blog/posts/*.md", {
  excerpt: true,
  transform: (raw) =>
    raw
      .sort(
        (a, b) => +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date),
      )
      .map(({ url, frontmatter, excerpt }) => ({
        title: frontmatter.title,
        url,
        excerpt,
      })),
});

<script setup>
import { data as posts } from "./posts.data";
</script>

transform is where you drop what the client does not need, which is why includeSrc and render are opt-in.

Full code: examples/core.md

Pattern 4: Vue components in Markdown

<script setup> at the top of a .md file makes its imports available to that page, and page-scoped imports code-split. Register a component globally only when many pages use it.

<script setup>
import StatusBadge from '../components/StatusBadge.vue'
</script>

# API Reference

<StatusBadge status="stable" /> This API is production-ready.

// .vitepress/theme/index.ts — global registration
export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component("StatusBadge", StatusBadge);
  },
};

Full code: examples/core.md

Pattern 5: Theme extension

Wrap DefaultTheme's Layout and fill its named slots. The slot list is long enough that most customization needs no fork.

<script setup>
import DefaultTheme from "vitepress/theme";
const { Layout } = DefaultTheme;
</script>

<template>
  <Layout>
    <template #doc-before><div class="author-banner">...</div></template>
    <template #doc-footer-before
      ><div class="feedback-widget">...</div></template
    >
  </Layout>
</template>

The full slot list is in reference.md.

Full code: examples/core.md

Pattern 6: Build hooks

Four hooks in config, running in order: transformPageData per page during render, transformHead per page after render, transformHtml per page on the final HTML string, and buildEnd once, for generating extra files into siteConfig.outDir.

export default defineConfig({
  transformPageData(pageData) {
    pageData.frontmatter.head ??= [];
    pageData.frontmatter.head.push([
      "meta",
      { property: "og:title", content: pageData.title },
    ]);
  },
  async buildEnd(siteConfig) {
    const posts = await createContentLoader("blog/*.md").load();
    // write an RSS feed or redirect map into siteConfig.outDir
  },
});

Full code: examples/core.md

Pattern 7: Markdown extensions

Containers, tabbed code groups, line highlighting and annotations, file snippets and partial includes, all on top of standard Markdown.

::: tip RECOMMENDATION
Containers are `info`, `tip`, `warning`, `danger` and `details`; the word after the type is the title.
:::

::: code-group

export default defineConfig({ title: "Docs" });

export default { title: "Docs" };

:::

<<< @/snippets/example.ts

<!--@include: ./shared/header.md-->

Line ranges highlight with a brace suffix on the language (ts{2-3}), and in-code annotations are // [!code focus], // [!code ++], // [!code --], // [!code warning] and // [!code error].

Full code: examples/core.md

Pattern 8: markdown-it plugins

markdown.config receives the fully-configured markdown-it instance, with VitePress's own plugins already registered — which is why plugins go here rather than into an instance of your own.

export default defineConfig({
  markdown: {
    lineNumbers: true,
    toc: { level: [1, 2, 3] },
    config: (md) => {
      md.use(markdownItFootnote);
    },
  },
});

Full code: examples/core.md

</patterns>

<red_flags>

Red flags

Breaks at runtime:

• window, document or a browser-only library reached outside onMounted or <ClientOnly> — the build pre-renders every page and crashes there.
• Config anywhere but .vitepress/config.ts — it is not found, and nothing reports that it was looked for.
• base without a leading and trailing slash ("/docs/") — VitePress errors.
• A loader file not ending in .data.ts, .data.js, .data.mts or .data.mjs — the .data suffix is what makes it a loader.
• A dead link anywhere — builds fail on them by default, and ignoreDeadLinks: true is a migration crutch rather than a setting to keep.
• useData() called outside a Vue setup context — it is a composable, not a global.
• Frontmatter outline given a bare number where the field takes [2, 3] or 'deep'.

Surprising behaviour:

• render: true on a large createContentLoader collection puts every page's full HTML in the client bundle.
• Forking the default theme layout instead of filling its slots turns every VitePress upgrade into a merge.
• Fetching at runtime what a data loader could have resolved at build time pays for the same data on every visit.
• A sidebar path prefix without its trailing slash matches more than intended ("/guide" also matches /guidelines).
• Without cleanUrls: true, every URL carries .html.
• sitemap without hostname generates a sitemap of empty URLs, and lastUpdated needs both the config flag and real git history — in CI that means an unshallow checkout.
• A flat sidebar array where sections need different navigation gives every page the same sidebar; the object form is keyed by prefix for that reason.
• A heavy import in a globally registered component loads on every page, which is what page-scoped imports avoid.
• <script setup> placed after Markdown content parses unreliably — put it first.
• Dynamic routes are resolved at build time by paths() in a [param].paths.ts file; they are not request-time routes.
• Subdirectory deployments need the matching --base at build time.
• createContentLoader silently skips non-Markdown files that match its glob.

</red_flags>