/web-meta-framework-vitepress

name: web-meta-framework-vitepress
description: VitePress 1.x — Vue-powered static site generator for documentation sites, built on Vite

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](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](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](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](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 d