Skip to content

@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 等),按需安装。

安装 ​

sh
pnpm add @neosjs/vitepress-theme
sh
npm i @neosjs/vitepress-theme
sh
yarn add @neosjs/vitepress-theme

快速上手 ​

以下用法即本站(NeosJS 文档站)的实际接入方式,可直接照搬到你的 VitePress 站点。

1. 扩展主题 ​

在 .vitepress/theme/index.ts 中通过 extends 继承该主题,并用自定义 Layout 接管布局(插槽见下文):

ts
// .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 Theme

2. 使用布局插槽 ​

主题的 Layout 暴露了四个扩展插槽:home-wave(首页底部波形区)、home-toggle-appearance(首页外观切换按钮)、aside-sponsors(文档侧边栏赞助位)、doc-bottom-after(文档内容底部)。

vue
<!-- .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 字段用于按环境启停导航项:

ts
// .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 可选字段:

ts
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 组件:

ts
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 并从预构建中排除:

ts
// .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:

ts
import NeosTheme from '@neosjs/vitepress-theme/theme-without-fonts'