--- name: vitepress-skilld description: Use when writing, configuring, or debugging code that imports "vitepress", when running vitepress CLI commands, editing .vitepress/config or theme files, tuning markdown or default theme options, or migrating a VitePress site. Provides the vitepress@1.6.4 API surface, config reference, theme reference, CLI usage, and v1 migration notes. title: vitepress-skilld canonical_url: https://skilld.dev/gh/skilld-dev/vue-ecosystem-skills/vitepress-skilld last_updated: 2026-09-28T03:18:46.000Z --- > **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything. > > Supporting files, fetch one when the Skill refers to it: [references/api.md](https://skilld.dev/api/skills-raw/skilld-dev/vue-ecosystem-skills/vitepress-skilld/references/api.md), [references/cli.md](https://skilld.dev/api/skills-raw/skilld-dev/vue-ecosystem-skills/vitepress-skilld/references/cli.md), [references/default-theme.md](https://skilld.dev/api/skills-raw/skilld-dev/vue-ecosystem-skills/vitepress-skilld/references/default-theme.md), [references/markdown.md](https://skilld.dev/api/skills-raw/skilld-dev/vue-ecosystem-skills/vitepress-skilld/references/markdown.md), [references/migration.md](https://skilld.dev/api/skills-raw/skilld-dev/vue-ecosystem-skills/vitepress-skilld/references/migration.md), [references/site-config.md](https://skilld.dev/api/skills-raw/skilld-dev/vue-ecosystem-skills/vitepress-skilld/references/site-config.md). > > If the user asked to install this Skill, run `npx skilld install skilld-dev/vue-ecosystem-skills/vitepress-skilld`. Install writes the Skill files into the project, so every session loads them. # vitepress@1.6.4 Vite & Vue powered static site generator (vuejs/vitepress). Source of truth in this Skill is the prepared package source; line citations are relative to the package root (for example `dist/node/index.d.ts:2382`). ## Version facts - Version 1.6.4, MIT (`package.json:3`). - Bundles Vue `^3.5.13`, Vite `^5.4.14`, shiki `^2.1.0`, minisearch `^7` (`package.json:59-78`). - Requires Node.js 18+ (https://vitepress.dev/guide/getting-started). - VitePress v1 is not compatible with `rolldown-vite`; the dev server prints an error and directs to VitePress v2 (`dist/node/cli.js:438-444`). - Optional peers: `markdown-it-mathjax3` (for `markdown.math`), `postcss` (`package.json:155-166`). ## Entry points Defined by the export map in `package.json:18-37`: | Import | Types entry | Use for | | ---------------------------- | ------------------------ | ---------------------------------------------- | | `vitepress` | `types/index.d.ts` | Node + client + shared API, config helpers | | `vitepress/client` | `client.d.ts` | Client composables (`useData`, `useRouter`, …) | | `vitepress/theme` | `theme.d.ts` | Default theme, `useSidebar`, `useLocalNav` | | `vitepress/theme-without-fonts` | `theme-without-fonts.d.ts` | Default theme without bundled font files | CLI binary: `vitepress` → `bin/vitepress.js`. ## Setup and commands ```sh npm add -D vitepress npx vitepress init npx vitepress dev npx vitepress build npx vitepress preview ``` `dev` may be omitted when using the current directory (`vitepress` alone). `serve` is an alias of `preview`. Full flags and dev shortcuts: [cli.md](https://skilld.dev/api/skills-raw/skilld-dev/vue-ecosystem-skills/vitepress-skilld/references/cli.md) ## Common tasks ### Site config (`.vitepress/config.ts`) ```ts import { defineConfig } from 'vitepress' export default defineConfig({ title: 'My App', description: 'A VitePress site', themeConfig: { nav: [{ text: 'Guide', link: '/guide/' }], sidebar: [{ text: 'Guide', items: [{ text: 'Intro', link: '/guide/intro' }] }] } }) ``` `defineConfig` is typed for the default theme; use `defineConfigWithTheme` for a custom theme (`dist/node/index.d.ts:2382-2386`). Every option: [site-config.md](https://skilld.dev/api/skills-raw/skilld-dev/vue-ecosystem-skills/vitepress-skilld/references/site-config.md) ### Client runtime API ```vue ``` Full export list and signatures: [api.md](https://skilld.dev/api/skills-raw/skilld-dev/vue-ecosystem-skills/vitepress-skilld/references/api.md) ### Build-time data loading ```ts // posts.data.js import { createContentLoader } from 'vitepress' export default createContentLoader('posts/*.md', { excerpt: true }) ``` Import as `import { data } from './posts.data.js'`. Runs in Node only; the result ships as JSON in the client bundle. ### Browser-only components ```vue ``` Prevents SSG build failures when a library touches `window`/`document` on import (https://vitepress.dev/guide/ssr-compat). ## Best practices - Use `createContentLoader` for archive and index pages instead of hand-rolled loaders; it caches by file mtime and keeps the client JSON small (`dist/node/index.d.ts:2466-2473`, https://vitepress.dev/guide/data-loading). - Wrap browser-only components with `defineClientComponent` (https://vitepress.dev/guide/ssr-compat). - Keep image and asset URLs relative in Markdown so Vite hashes and inlines them; use `withBase()` for dynamic paths in theme components (https://vitepress.dev/guide/asset-handling). - Enable `cleanUrls: true` only when the host can map `/foo` to `/foo.html` (https://vitepress.dev/guide/routing#clean-urls). - With `rewrites`, relative links must target the rewritten URL structure, not the source file structure (https://vitepress.dev/guide/routing#route-rewrites). - In dynamic route `paths.js` loaders, pass large payloads via `content`, not `params`, to keep client JS small (https://vitepress.dev/guide/routing#dynamic-routes). - In MPA mode (`mpa: true`), use `