vitepress-skilld

[email protected]

由 Vite 和 Vue 驱动的静态站点生成器（vuejs/vitepress）。本 Skill 的权威来源是已准备好的软件包源代码；行号引用相对于软件包根目录（例如 dist/node/index.d.ts:2382）。

版本信息

• 版本 1.6.4，MIT（package.json:3）。
• 捆绑 Vue ^3.5.13、Vite ^5.4.14、shiki ^2.1.0、minisearch ^7（package.json:59-78）。
• 需要 Node.js 18+（https://vitepress.dev/guide/getting-started）。
• VitePress v1 与 rolldown-vite 不兼容；开发服务器会打印错误并引导用户使用 VitePress v2（dist/node/cli.js:438-444）。
• 可选对等依赖：markdown-it-mathjax3（用于 markdown.math）、postcss（package.json:155-166）。

入口点

由 package.json:18-37 中的导出映射定义：

导入	类型入口	用途
vitepress	types/index.d.ts	Node、客户端和共享 API、配置辅助函数
vitepress/client	client.d.ts	客户端组合式函数（useData、useRouter，…）
vitepress/theme	theme.d.ts	默认主题、useSidebar、useLocalNav
vitepress/theme-without-fonts	theme-without-fonts.d.ts	不包含捆绑字体文件的默认主题

CLI 二进制文件：vitepress → bin/vitepress.js。

设置和命令

npm add -D vitepress
npx vitepress init
npx vitepress dev
npx vitepress build
npx vitepress preview

在当前目录中使用时，可以省略 dev（单独使用 vitepress 即可）。 serve 是 preview 的别名。完整标志和开发快捷方式： cli.md

常见任务

站点配置（.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 针对默认主题提供类型支持；自定义主题请使用 defineConfigWithTheme<CustomThemeConfig> （dist/node/index.d.ts:2382-2386）。所有选项： site-config.md

客户端运行时 API

<script setup>
import { useData, useRouter, withBase } from 'vitepress'
const { page, frontmatter, isDark, hash } = useData()
const router = useRouter()
</script>

完整的导出列表和签名：api.md

构建时数据加载

// posts.data.js
import { createContentLoader } from 'vitepress'
export default createContentLoader('posts/*.md', { excerpt: true })

以 import { data } from './posts.data.js' 的形式导入。仅在 Node 中运行；结果会以 JSON 的形式随客户端 bundle 一同发布。

仅限浏览器的组件

<script setup>
import { defineClientComponent } from 'vitepress'
const Chart = defineClientComponent(() => import('./Chart.vue'))
</script>

当库在导入时访问 window/document 时，可避免 SSG 构建失败（https://vitepress.dev/guide/ssr-compat）。

最佳实践

• 归档页和索引页应使用 createContentLoader，而不是手动编写加载器；它会按文件 mtime 缓存，并保持客户端 JSON 精简 （dist/node/index.d.ts:2466-2473、https://vitepress.dev/guide/data-loading）。
• 使用 defineClientComponent 包装仅限浏览器的组件 （https://vitepress.dev/guide/ssr-compat）。
• Markdown 中的图片和资源 URL 应使用相对路径，以便 Vite 为其生成哈希并内联；主题组件中的动态路径请使用 withBase() （https://vitepress.dev/guide/asset-handling）。
• 仅当托管服务能够将 /foo 映射到 /foo.html 时，才启用 cleanUrls: true （https://vitepress.dev/guide/routing#clean-urls）。
• 使用 rewrites 时，相对链接必须指向重写后的 URL 结构，而不是源文件结构 （https://vitepress.dev/guide/routing#route-rewrites）。
• 在动态路由 paths.js 加载器中，应通过 content 而不是 params 传递较大的数据载荷，以保持客户端 JS 精简 （https://vitepress.dev/guide/routing#dynamic-routes）。
• 在 MPA 模式（mpa: true）下，使用 <script client> 实现交互；普通的 <script setup> 仅用于服务端模板处理 （https://vitepress.dev/guide/mpa-mode）。
• 使用 _render 钩子将页面排除在本地搜索之外 （types/default-theme.d.ts:451-455）。

更深入的参考资料

• api.md：vitepress、vitepress/client、vitepress/theme 的所有导出项、数据加载器类型、主题接口。
• site-config.md：UserConfig 字段、构建钩子、SiteConfig、mergeConfig。
• default-theme.md：DefaultTheme.Config、导航栏、侧边栏、搜索（本地和 algolia）、主题扩展。
• markdown.md：markdown 选项、shiki 配置、容器、数学公式、createMarkdownRenderer。
• cli.md：命令、标志、开发快捷方式、脚手架。
• migration.md：v0 → v1 的重大变更，以及在 1.6.4 中仍可见的弃用项。

特定版本的变更

修改旧配置时，请优先留意以下内容；详情和引用见 migration.md：

• 重大变更（v1.0.0-rc.9）：已移除 pathname:// 协议；请使用 target="_self" 或 target="_blank" (https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md)。
• 重大变更（v1.0.0）：侧边栏的 children 已重命名为 items；顶层项目不再接受 link (https://vitepress.dev/guide/migration-from-vitepress-0)。
• 重大变更（v1.0.0-alpha.44）：collapsible 已替换为 collapsed: boolean (CHANGELOG)。
• 重大变更（v1.0.0-alpha.57）：markdown.headers 默认禁用； 除非启用，否则 PageData.headers 为空 (CHANGELOG)。
• 启用 markdown.headers 时，提取级别默认为 [2, 3] (dist/node/index.d.ts:1769-1786)。
• 新增（v1.1.0）：useData().hash 响应式 URL 哈希 (dist/client/index.d.ts:79-83)。
• 新增（v1.4.0）：onAfterPageLoad 路由钩子 (dist/client/index.d.ts:36-38)。
• 新增（v1.3.0）：appearance: 'force-auto' (types/shared.d.ts:119-124)。
• 在 1.6.4 中已弃用：Theme.setup、Theme.NotFound (dist/client/index.d.ts:96-103)、outlineTitle、lastUpdatedText、 algolia 主题选项 (types/default-theme.d.ts:36-77,139-141)。