AI 技能人工智能【免费下载链接】skillsAnthony Fus curated collection of agent skills.项目地址https://gitcode.com/gh_mirrors/skills11/skills点击查看免费下载当 VitePress 默认主题的导航、侧边栏、首页版式无法满足项目需要时不必修改源码而是可以通过官方主题接口从零构建一套完全属于你自己的主题。本文以本仓库skills 项目中 VitePress Agent Skill 的 theme-custom 参考文档 为核心骨架系统讲解主题入口、Theme接口、Layout组件、运行时 API、路由钩子、组件注册与主题分发等完整流程并结合仓库中同目录的 theme-config、theme-customization、core-config、advanced-ssr 等参考文档交叉印证。读完本文你将具备从零编写、扩展、类型化并发布一个 VitePress 自定义主题的完整能力。版本前提本仓库的 VitePress Skill 基于 VitePress 2.0.0-alpha.20 生成见 SKILL.md文中标注 (v2) 的能力均为该版本新增或变更如defineConfigWithTheme已废弃、setup主题钩子与路由钩子为 v2 新特性。什么时候需要从零构建主题VitePress 默认主题对文档站点开箱即用但存在两类场景需要自定义主题深度定制默认主题不改写整个主题而是通过extends: DefaultTheme叠加布局插槽、CSS 变量、全局组件与自定义字体。此类方案详见 theme-customization本文末尾也会给出与默认主题衔接的实践。从零构建主题当产品形态与文档差异巨大营销官网、落地页、作品集、内部工具台时默认主题的任何微调都无法满足要求此时应当构建一套全新的主题这正是本文的核心主题。从零构建的核心收益是页面结构、路由、站点元数据、深色模式等能力由 VitePress 的运行时 API 提供你只需专注编写自己的Layout组件与配套页面组件站点依旧享受 Markdown 文件路由、SSG 预渲染与 SPA 热更新HMR的全部特性。主题入口.vitepress/theme/index.tsVitePress 约定自定义主题的入口文件位于.vitepress/theme/index.ts。该文件默认导出一个Theme对象Layout字段指向主题的根布局组件// .vitepress/theme/index.ts import Layout from ./Layout.vue export default { Layout, enhanceApp({ app, router, siteData }) { // Register global components, plugins, etc. } }几个要点入口文件必须位于.vitepress/theme/目录下文件名支持index.ts也可用.js、.mjs、.mts。Layout是必填字段指向你的根布局组件通常是Layout.vue。enhanceApp是可选字段接收EnhanceAppContext用于注册全局组件、Vue 插件与依赖注入。在检查一个 VitePress 项目时先看.vitepress/theme/目录即可判断它是否使用了自定义主题这也是 SKILL.md 中列出的检查要点。Theme 接口四大字段与上下文对象Theme接口是自定义主题的契约官方定义如下interface Theme { // Required: Root layout component Layout: Component // Optional: Enhance Vue app instance enhanceApp?: (ctx: EnhanceAppContext) Awaitablevoid // Optional (v2): runs inside the root components setup() setup?: () void // Optional: Extend another theme (its enhanceApp setup run first) extends?: Theme } interface EnhanceAppContext { app: App // Vue app instance router: Router // VitePress router siteData: RefSiteData // Site-level metadata }逐字段解读字段必填作用与行为Layout是根布局组件负责渲染页面外壳与Content /。enhanceApp否在应用初始化阶段调用可注册全局组件、安装插件、provide数据在服务端与客户端都会执行SSG 构建与浏览器水合各一次。setup否v2运行在根组件setup()内部可以安全调用useData()等组合式 API同样会随 SSR/SSG 执行浏览器专属逻辑应放在onMounted内详见 advanced-ssr。extends否继承另一个主题被继承主题的enhanceApp与setup会先于当前主题执行适合在默认主题或其他第三方主题之上叠加改造。EnhanceAppContext中的app是 Vue 应用实例app.component、app.use、app.provide均可用router是 VitePress 内置路由详见下文路由变更钩子siteData是站点级元数据的响应式引用。最小可用 Layout必须渲染Content /Layout组件是主题的灵魂它的职责是提供页面外壳页头、导航、主区域、页脚并在内容位置渲染Content /。Content /是 VitePress 内置组件负责把当前路由的 Markdown 渲染结果注入到布局中——没有它页面将没有正文。!-- .vitepress/theme/Layout.vue -- script setup import { useData } from vitepress const { page, frontmatter } useData() /script template div classlayout header navMy Site/nav /header main div v-ifpage.isNotFound h1404 - Page Not Found/h1 /div div v-else-iffrontmatter.layout home h1Welcome!/h1 /div article v-else Content / /article /main footer p© 2024 My Site/p /footer /div /template这段代码演示了三种典型分支404 页通过page.isNotFound判断当前路由是否为未找到页面渲染自定义的 404 提示。首页/特殊布局通过frontmatter.layout home判断页面 frontmatter 中声明的layout类型渲染完全不同的版式这里只是一个欢迎标题。普通文档页其余情况渲染article并放入Content /正文由 VitePress 处理。useData()是主题开发最重要的组合式 API它暴露的响应式数据贯穿整个布局逻辑详见下一节。这种按frontmatter.layout分发到不同页面组件的模式就是后面主题感知布局的雏形。运行时 APIuseData、useRoute与useRouter自定义主题中访问站点数据的入口全部来自vitepress包导出的组合式 APIscript setup import { useData, useRoute, useRouter } from vitepress // Page and site data const { site, // Site config (title, description, etc.) theme, // Theme config page, // Current page data frontmatter, // Current page frontmatter title, // Page title description, // Page description lang, // Current language isDark, // Dark mode state params // Dynamic route params } useData() // Routing const route useRoute() const router useRouter() // Navigate programmatically const goToGuide () router.go(/guide/) /script各字段语义字段类型说明siteRefSiteData站点级配置如title、description、base、lang等。themeRefThemeConfigconfig.themeConfig中声明的主题配置类型可由你的主题定义见主题配置类型一节。pageRefPageData当前页面的完整数据包含isNotFound、headers、relativePath、title等。frontmatterRefRecordstring, any当前页面 Markdown 顶部的 frontmatter可读取layout等自定义字段。titleRefstring页面标题。descriptionRefstring页面描述。langRefstring当前语言i18n 场景下随语言切换。isDarkRefboolean深色模式状态可读可写切换主题时直接赋值即可。paramsRefRecordstring, string动态路由参数配合动态路由使用参见 features-dynamic-routes。useRoute()返回当前路由信息路径、hash、查询参数等useRouter()返回路由实例可通过router.go(/guide/)编程式跳转。在布局组件的模板中你也可以直接使用 VitePress 的Content等内置组件见后文。路由变更钩子v2onBeforeRouteChange与onAfterRouteChangeVitePress 2 允许在路由实例上直接挂载导航钩子用于在页面切换前后执行逻辑埋点、权限校验、滚动恢复、取消导航等。钩子同样可以通过enhanceApp的router参数拿到const router useRouter() router.onBeforeRouteChange (to) { /* return false to cancel */ } router.onAfterRouteChange (to) console.log(navigated to, to)关键行为onBeforeRouteChange的to参数是目标路由信息返回false即可取消本次导航onAfterRouteChange在导航完成后触发适合记录浏览历史、发送分析事件在enhanceApp({ router })中挂载钩子时无需useRouter()上下文直接提供路由实例与主题的setup钩子配合可以监听页面数据变化——例如在 theme-customization 的示例中setup()内watch(() page.value.relativePath, ...)即可在每次切换页面时感知当前文档路径。内置组件Content与ClientOnly主题开发中会频繁用到两个由vitepress导出的内置组件script setup import { Content } from vitepress /script template !-- Renders markdown content -- Content / !-- Renders slot only on client (SSR-safe) -- ClientOnly NonSSRComponent / /ClientOnly /templateContent /渲染当前页面的 Markdown 内容任何自定义 Layout 都必须渲染它否则正文丢失。ClientOnly其插槽内容只在客户端渲染SSR/SSG 阶段安全。凡是不兼容服务端渲染的组件依赖window、document或浏览器 API 的组件都应包裹在ClientOnly内避免构建期报错或水合不一致。更系统的 SSR 兼容策略onMounted内访问浏览器 API、defineClientComponent动态加载、import.meta.env.SSR分支参见 advanced-ssr。需要说明ClientOnly内的组件不会参与构建期的服务端渲染若其中使用了 iconify 图标需要在 core-config 的icons.include中显式声明以便构建管线收集图标样式。在既有主题之上扩展extends如果不想从零开始可以先继承默认主题或其他第三方主题再叠加自己的定制逻辑。这是既保留默认主题全部能力、又注入自定义行为最直接的桥梁// .vitepress/theme/index.ts import DefaultTheme from vitepress/theme export default { extends: DefaultTheme, enhanceApp({ app }) { // Your customizations } }extends的执行顺序是被继承主题先执行enhanceApp与setup当前主题后执行因此当前主题的注册可以覆盖或补充父主题的行为。默认主题还导出一系列可覆盖的布局插槽与 CSS 变量theme-customization 详细讲解了插槽注入aside-outline-before、doc-before等、渲染函数h(DefaultTheme.Layout, null, { slotName: () ... })与 Vite alias 替换内部组件如重写VPNavBar.vue三种覆盖手段。若你的目标是保留默认主题 局部增强请优先阅读该文档而不是重写整个主题。注册全局组件与插件enhanceApp的典型用法enhanceApp是主题向 Vue 应用注入能力的统一入口。三种最常见的操作// .vitepress/theme/index.ts import Layout from ./Layout.vue import GlobalComponent from ./GlobalComponent.vue export default { Layout, enhanceApp({ app }) { // Register global component app.component(GlobalComponent, GlobalComponent) // Register plugin app.use(MyPlugin) // Provide/inject app.provide(key, value) } }app.component(...)注册全局组件注册后可直接在任何 Markdown 文件中以GlobalComponent /形式使用Vue 组件嵌入 Markdown 的能力参见 features-vue。app.use(...)安装 Vue 插件如状态管理、UI 组件库。app.provide(...)建立provide/inject依赖注入供布局、页面组件或 Markdown 中的组件消费。注意enhanceApp在服务端与客户端都会执行因此不能在里面直接访问浏览器 APIwindow/document。若插件本身在导入时就触碰浏览器 API需要配合下面的异步方案。异步 enhanceApp按环境分支动态加载某些插件只能在浏览器端运行例如图表库、编辑器、与 DOM 深度绑定的 UI 库。此时可以让enhanceApp变为异步函数并用import.meta.env.SSR判断当前是服务端还是客户端export default { Layout, async enhanceApp({ app }) { if (!import.meta.env.SSR) { // Client-only plugin const plugin await import(browser-only-plugin) app.use(plugin.default) } } }这里import.meta.env.SSR在 VitePress 服务端渲染/SSG 构建阶段为true在浏览器水合阶段为false。把浏览器专属插件放进if (!import.meta.env.SSR)分支服务端构建时不会导入该模块避免window is not defined之类的构建错误客户端水合时动态导入并安装保证功能可用且不拖慢首屏构建。该模式同样适用于组件与库advanced-ssr 给出了组件内onMounted动态导入、defineClientComponent等更细粒度的方案。主题感知布局按 frontmatter 分发页面组件真实站点通常需要多套页面版式首页Hero 特性卡片、文档页侧边栏 正文、独立页自定义落地页、404 页。推荐的做法是拆分成多个页面组件在根Layout中依据page.isNotFound与frontmatter.layout分发script setup import { useData } from vitepress import Home from ./Home.vue import Doc from ./Doc.vue import Page from ./Page.vue import NotFound from ./NotFound.vue const { page, frontmatter } useData() /script template NotFound v-ifpage.isNotFound / Home v-else-iffrontmatter.layout home / Page v-else-iffrontmatter.layout page / Doc v-else / /template各组件职责建议组件触发条件职责NotFound.vuepage.isNotFound404 页面含引导链接如返回首页。Home.vuefrontmatter.layout home营销首页一般由 frontmatter 数据驱动渲染 Hero、特性区。Page.vuefrontmatter.layout page全宽自定义页不带文档侧边栏。Doc.vue其余情况默认文档正文页渲染Content /、页头导航与页脚。其中每个页面组件内部负责自己的Content /渲染与样式。这样将页面外壳与内容版式解耦后续新增版式只需在Layout中加一个分支、再写一个组件即可。将主题发布为 npm 包主题不仅可以在单项目内使用还可以封装成 npm 包供多个站点复用例如团队维护一套公司级文档主题。发布侧只需导出主题对象与类型// my-theme/index.ts import Layout from ./Layout.vue export default { Layout } // Export types for config export type { ThemeConfig } from ./types消费侧有两种接入方式// .vitepress/theme/index.ts import Theme from my-vitepress-theme export default Theme // Or extend it export default { extends: Theme, enhanceApp({ app }) { // Additional customization } }直接使用默认导出主题对象即完成接入扩展使用通过extends在第三方主题之上继续叠加enhanceApp、setup或自定义Layout实现主题即插件的分层组合。打包时注意主题包内若有.vue组件与 CSS应确保构建产物能被消费方的 Vite 直接处理通常按 Vue 单文件组件与原生 CSS 发布即可或提供已编译版本。发布主题时同时导出ThemeConfig类型见下节能显著提升使用方的配置体验。主题配置类型defineConfigThemeConfig为了给使用方提供类型安全的themeConfig主题应导出自己的配置类型使用方在defineConfig中传入该类型参数即可获得完整的类型提示与校验// .vitepress/config.ts import { defineConfig } from vitepress import type { ThemeConfig } from my-theme export default defineConfigThemeConfig({ themeConfig: { // Type-checked theme config } })两点版本注意均为 v2 行为见 core-configdefineConfigWithTheme已废弃请一律使用defineConfigThemeConfig传递类型参数你的主题应负责声明ThemeConfig的字段并导出类型。作为对照默认主题的ThemeConfig覆盖导航nav、侧边栏sidebar、搜索search、社交链接socialLinks、页脚footer、编辑链接editLink等完整字段说明见 theme-config。在自定义主题内部通过useData()解构出的theme字段读取的就是这份经过类型约束的themeConfig从而把配置声明与运行时消费两端都用类型串起来。与默认主题定制方案的取舍最后把两条路线放在一起对比帮助你在实际项目中做选择需求推荐方案参考文档换品牌色、字体、背景覆盖 CSS 变量--vp-c-brand-1等甚至免去组件覆盖实现毛玻璃导航栏theme-customization在固定位置插入内容侧边栏上方、正文前后、页脚前默认主题布局插槽如doc-before、aside-outline-beforetheme-customization注册全局组件、安装插件extends: DefaultThemeenhanceApp本文在既有主题之上扩展一节替换默认主题内部组件如导航栏Viteresolve.alias匹配VPNavBar.vue等theme-customization页面版式与默认主题完全不同从零构建Layout 主题感知分发本文主体Key Points 速查主题必须通过.vitepress/theme/index.ts导出Layout组件否则站点无法渲染Content /是渲染 Markdown 正文的唯一入口Layout中必须渲染它useData()提供site、theme、page、frontmatter、title、lang、isDark等响应式数据是主题数据访问的核心 APIenhanceApp在服务端与客户端都会运行浏览器专属逻辑请用import.meta.env.SSR分支或放入onMounted详见 advanced-ssrClientOnly用于包裹非 SSR 兼容组件避免构建错误与水合不一致用extends复用默认主题或其他主题被继承主题的enhanceApp/setup先执行v2 新增主题setup钩子在根组件setup()内运行路由实例上的onBeforeRouteChange/onAfterRouteChange用于导航拦截与监听主题配置类型请使用defineConfigThemeConfigdefineConfigWithTheme已废弃。本文对应的完整参考与配套资料可在仓库 skills/vitepress/references/theme-custom.md 及其同目录文档中继续深入阅读。赞分享AI 技能人工智能【免费下载链接】skillsAnthony Fus curated collection of agent skills.项目地址https://gitcode.com/gh_mirrors/skills11/skills点击查看免费下载相关推荐VitePress 自定义主题完全指南从零构建、分发与消费自己的主题VitePress 自定义主题完全指南从零构建、分发与消费自己的主题 VitePress 默认主题开箱即用但当你需要完全掌控站点的外观与交互时自定义主题是前端文档VitePress 自定义主题完全指南Theme 接口、布局构建与主题分发消费VitePress 自定义主题完全指南Theme 接口、布局构建与主题分发消费 导读 本文基于 VitePress 官方指南中的《使用自定义主题》章节系统讲前端文档VitePress 自定义主题完全指南从主题入口到布局构建与分发VitePress 自定义主题完全指南从主题入口到布局构建与分发 导读 本指南基于 VitePress 官方中文文档中的自定义主题章节展开系统讲解如何通前端文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考