vitepress-skilld
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.
How do I install this agent skill?
npx skills add https://github.com/skilld-dev/vue-ecosystem-skills --skill vitepress-skilldIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides comprehensive documentation and technical references for VitePress v1.6.4. It includes details on CLI commands, API surfaces, configuration, and migration. The content is strictly informational and follows official development guidelines without any detected security risks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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(formarkdown.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
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
Common tasks
Site config (.vitepress/config.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<CustomThemeConfig> for a custom theme
(dist/node/index.d.ts:2382-2386). Every option:
site-config.md
Client runtime API
<script setup>
import { useData, useRouter, withBase } from 'vitepress'
const { page, frontmatter, isDark, hash } = useData()
const router = useRouter()
</script>
Full export list and signatures: api.md
Build-time data loading
// 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
<script setup>
import { defineClientComponent } from 'vitepress'
const Chart = defineClientComponent(() => import('./Chart.vue'))
</script>
Prevents SSG build failures when a library touches window/document on
import (https://vitepress.dev/guide/ssr-compat).
Best practices
- Use
createContentLoaderfor 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: trueonly when the host can map/footo/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.jsloaders, pass large payloads viacontent, notparams, to keep client JS small (https://vitepress.dev/guide/routing#dynamic-routes). - In MPA mode (
mpa: true), use<script client>for interactivity; plain<script setup>is server-side templating only (https://vitepress.dev/guide/mpa-mode). - Exclude pages from local search with the
_renderhook (types/default-theme.d.ts:451-455).
Deeper references
- api.md: every export from
vitepress,vitepress/client,vitepress/theme, data loader types, theme interface. - site-config.md:
UserConfigfields, build hooks,SiteConfig,mergeConfig. - default-theme.md:
DefaultTheme.Config, nav, sidebar, search (local and algolia), theme extension. - markdown.md:
markdownoptions, shiki setup, containers, math,createMarkdownRenderer. - cli.md: commands, flags, dev shortcuts, scaffolding.
- migration.md: v0 → v1 breaking changes and deprecations still visible in 1.6.4.
Version-specific changes
Prioritize these when touching old configs; details and citations in migration.md:
- BREAKING (v1.0.0-rc.9):
pathname://protocol removed; usetarget="_self"ortarget="_blank"(https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md). - BREAKING (v1.0.0): sidebar
childrenrenamed toitems; top-level items no longer acceptlink(https://vitepress.dev/guide/migration-from-vitepress-0). - BREAKING (v1.0.0-alpha.44):
collapsiblereplaced bycollapsed: boolean(CHANGELOG). - BREAKING (v1.0.0-alpha.57):
markdown.headersdisabled by default;PageData.headersis empty unless enabled (CHANGELOG). - When
markdown.headersis enabled, extraction levels default to[2, 3](dist/node/index.d.ts:1769-1786). - NEW (v1.1.0):
useData().hashreactive URL hash (dist/client/index.d.ts:79-83). - NEW (v1.4.0):
onAfterPageLoadrouter hook (dist/client/index.d.ts:36-38). - NEW (v1.3.0):
appearance: 'force-auto'(types/shared.d.ts:119-124). - Deprecated in 1.6.4:
Theme.setup,Theme.NotFound(dist/client/index.d.ts:96-103),outlineTitle,lastUpdatedText,algoliatheme options (types/default-theme.d.ts:36-77,139-141).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/skilld-dev/vue-ecosystem-skills/vitepress-skilld">View vitepress-skilld on skillZs</a>