@knewbeing/vitepress-plugin-index

为 VitePress 提供文档索引功能的插件：自动构建文章标签云、文章列表并支持多语言 UI。

扫描 Markdown 文件的 frontmatter 元数据，生成可供客户端组件消费的文档索引数据，支持标签筛选、分类浏览等功能。

版权声明 / Copyright

本包代码派生自 @nolebase/vitepress-plugin-index（MIT 许可证）。
原始版权归 nolebase 所有。
由 knewbeing（知在，[email protected]）改进并重新发布，修改部分仍遵循 MIT 许可证。

This package is derived from @nolebase/vitepress-plugin-index (MIT License).
Original copyright belongs to nolebase.
Improved and republished by knewbeing ([email protected]). Modifications remain under MIT License.

功能特性 / Features

• 📚 文档索引 — 扫描所有 Markdown 文件，提取 frontmatter 元数据构建索引
• 🏷 标签系统 — 统计每个标签下的文章数量，支持标签云展示
• 🔍 标签过滤 — 通过 useIndexTagsStore 实现响应式标签筛选
• 🌐 多语言 UI — 内置 i18n 支持，包含简体中文、繁体中文、英语等
• 🛠 VitePress 集成 — 提供 vitepress 入口，包含 Vite 插件和配置助手
• 🎨 客户端组件 — 提供开箱即用的索引展示 Vue 组件和样式

安装 / Installation

npm install @knewbeing/vitepress-plugin-index
# or
pnpm add @knewbeing/vitepress-plugin-index

快速开始 / Quick Start

1. 注册 VitePress 插件

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import { NolebaseIndexPlugin } from '@knewbeing/vitepress-plugin-index/vitepress'

export default defineConfig({
  vite: {
    plugins: [
      NolebaseIndexPlugin(),
    ],
  },
})

2. 注册客户端组件

// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import { NolebaseIndexPlugin } from '@knewbeing/vitepress-plugin-index/client'
import '@knewbeing/vitepress-plugin-index/client/style.css'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.use(NolebaseIndexPlugin)
  },
} satisfies Theme

模块入口 / Module Exports

| 入口 | 说明 | |------|------| | ./client | Vue 组件和 composables（客户端使用） | | ./client/style.css | 组件样式 | | ./locales | 多语言文本定义 | | ./vitepress | VitePress Vite 插件（构建时使用） |

标签 Store / Tags Store

import { useIndexTagsStore } from '@knewbeing/vitepress-plugin-index/client/useIndexTagsStore'

const tagsStore = useIndexTagsStore()

// 获取所有标签及计数
console.log(tagsStore.tags) // [{ name: 'Vue', count: 12 }, ...]

// 切换选中标签
tagsStore.toggleTag('Vue')

// 获取当前选中标签
console.log(tagsStore.selectedTag)

许可证 / License

MIT

相关链接 / Links

• npm
• 源码仓库
• 原始项目