@neosjs/vitepress-theme
NeosJS 的 VitePress 主题:在默认主题基础上扩展了首页波形区、侧栏赞助位、文档底部、首页外观切换等布局插槽,以及 showAds / showJobs 等中文化站点配置项,并内置一批可复用的 VP 组件(首页 Hero / Features、团队页、赞助区、Badge 等)。本站(NeosJS 文档站)即是该主题的使用示例。
环境要求
面向 VitePress 1.x。部分 Markdown 扩展(容器、脚注、公式等)依赖可选 peer 依赖(markdown-it-container、markdown-it-footnote、markdown-it-mathjax3 等),按需安装。
安装
pnpm add @neosjs/vitepress-themenpm i @neosjs/vitepress-themeyarn add @neosjs/vitepress-theme快速上手
以下用法即本站(NeosJS 文档站)的实际接入方式,可直接照搬到你的 VitePress 站点。
1. 扩展主题
在 .vitepress/theme/index.ts 中通过 extends 继承该主题,并用自定义 Layout 接管布局(插槽见下文):
// .vitepress/theme/index.ts
import type { EnhanceAppContext, Theme } from 'vitepress'
import NeosTheme from '@neosjs/vitepress-theme'
import MyLayout from './Layout.vue'
import './styles/index.css'
export default {
extends: NeosTheme,
Layout: MyLayout,
enhanceApp({ app }: EnhanceAppContext) {
// 注册站点自己的全局组件
// app.component('ComponentsDemo', ComponentsDemo)
}
} satisfies Theme2. 使用布局插槽
主题的 Layout 暴露了四个扩展插槽:home-wave(首页底部波形区)、home-toggle-appearance(首页外观切换按钮)、aside-sponsors(文档侧边栏赞助位)、doc-bottom-after(文档内容底部)。
<!-- .vitepress/theme/Layout.vue -->
<script setup lang="ts">
import NeosTheme from '@neosjs/vitepress-theme'
import VPFooter from '@neosjs/vitepress-theme/dist/components/VPFooter.vue'
import HomeWave from './components/HomeWave.vue'
import SponsorsAside from './components/SponsorsAside.vue'
import SwitchAppearance from './components/SwitchAppearance.vue'
const { Layout } = NeosTheme
</script>
<template>
<Layout>
<template #home-wave>
<HomeWave />
</template>
<template #aside-sponsors>
<SponsorsAside />
</template>
<template #doc-bottom-after>
<VPFooter />
</template>
<template #home-toggle-appearance>
<SwitchAppearance />
</template>
</Layout>
</template>3. 配置 themeConfig
主题在 VitePress 默认 themeConfig 之上追加了 showAds / showJobs 等开关(控制侧边栏赞助区块与招聘区块的渲染,false 即关闭),并对 nav 条目扩展了 enabled 字段用于按环境启停导航项:
// .vitepress/config.ts
import { defineConfig } from 'vitepress'
export default defineConfig({
lang: 'zh-CN',
title: 'NeosJS',
srcDir: 'src',
appearance: 'dark', // 默认暗色模式
themeConfig: {
logo: { src: '/pwa-64x64.png', width: 24, height: 24 },
showAds: false, // 关闭侧边栏赞助区块
showJobs: false, // 关闭招聘区块
nav, // 侧边栏/导航:类型从 '@neosjs/vitepress-theme' 导入 NavItem
sidebar,
outlineTitle: '本页目录',
outline: [2, 3],
darkModeSwitchLabel: '切换主题',
lightModeSwitchTitle: '切换到浅色模式',
darkModeSwitchTitle: '切换到深色模式',
docFooter: { prev: '上一篇', next: '下一篇' },
notFound: {
title: '页面不存在哟',
quote: '页面不存在',
linkLabel: '返回首页',
linkText: '返回首页'
},
lastUpdated: {
text: '更新于',
formatOptions: { dateStyle: 'medium', timeStyle: 'short' }
},
socialLinks: [
{ icon: 'github', link: 'https://github.com/neosjs' }
]
}
})nav 的类型直接从主题导入,条目支持 enabled 可选字段:
import type { NavItem } from '@neosjs/vitepress-theme'
export const nav: NavItem[] = [
{ text: '首页', link: '/' },
{ text: '指南', activeMatch: '^/guide/', link: '/guide/' },
{ text: '更多', items: [/* ... */] }
]4. 暗色模式切换
VitePress 原生的 appearance 配置即生效(如上 appearance: 'dark')。本站还在 Layout.vue 中通过 useData() 的 isDark 配合 View Transitions API 实现了圆形扩散的明暗切换动画,并把切换函数注入给首页的 SwitchAppearance 组件:
import { useData } from 'vitepress'
import { provide } from 'vue'
const { isDark } = useData()
provide('toggle-appearance', async ({ clientX: x, clientY: y }: MouseEvent) => {
isDark.value = !isDark.value
// 配合 View Transitions API 实现 clipPath 扩散动画(见 VitePress 官方示例)
})5. SSR 构建备注
若构建时出现 SSR 外部化报错,可参考本站把主题加入 ssr.noExternal 并从预构建中排除:
// .vitepress/config.ts
export default defineConfig({
vite: {
ssr: {
noExternal: ['@neosjs/vitepress-theme']
},
optimizeDeps: {
exclude: ['@neosjs/vitepress-theme']
}
}
})API / 导出
| 入口 / 导出 | 说明 |
|---|---|
. 或 ./theme | 主题默认导出(Theme 对象,含 Layout 与 enhanceApp) |
./theme-without-fonts | 不内置字体样式的主题入口 |
./mdPlugins | 主题配套的 Markdown 插件集合入口 |
VPButton、VPImage、VPSponsors、VPDocAsideSponsors | 按钮 / 图片 / 赞助区组件 |
VPHomeHero、VPHomeFeatures、VPHomeSponsors | 首页 Hero / Features / 赞助组件 |
VPTeamPage、VPTeamPageSection、VPTeamPageTitle、VPTeamMembers | 团队页组件 |
VPIconSun、VPIconMoon、VPFooter | 图标与页脚组件 |
useSidebar、useSponsor | 侧边栏 / 赞助数据 composables |
Badge | 全局注册的徽章组件(enhanceApp 内自动注册) |
NavItem 等类型 | 导航类型定义,条目支持 enabled?: boolean |
主题默认入口包含字体样式;对字体加载有要求的站点可改用 ./theme-without-fonts:
import NeosTheme from '@neosjs/vitepress-theme/theme-without-fonts'