vitepress-plugin-doc-analysis

这是一个适用于 vitepress 的 Vite 插件，在 vitepress 启动后分析 Markdown 文档。

✨ Feature

• 🚀 自动分析 Markdown 文档信息，挂载到 themeConfig.docAnalysisInfo
• 🚀 支持 locales 国际化的文档分析，挂载到 locales.[lang].themeConfig.docAnalysisInfo

🕯️ Install

安装 vitepress-plugin-doc-analysis 插件

1# 推荐使用 pnpm
2pnpm i vitepress-plugin-doc-analysis
3# or yarn
4yarn add vitepress-plugin-doc-analysis
5# or npm
6npm install vitepress-plugin-doc-analysis

添加 vitepress-plugin-doc-analysis 插件到 .vitepress/config.ts

1import { defineConfig } from "vitepress";
2import DocAnalysis from "vitepress-plugin-doc-analysis";
3
4export default defineConfig({
5  vite: {
6    plugins: [DocAnalysis(/* options */)],
7  },
8});

说明：该插件仅限项目启动时生效，已改动或新添加的 Markdown 需要重启项目才能生效。

插件默认忽略 ["node_modules", "dist", ".vitepress", "public"] 目录下的文件，且只扫描 Markdown 文档。

🛠️ Options

name	description	type	default
ignoreList	忽略的文件/文件夹列表，支持正则表达式	string[]	[]
path	指定扫描的根目录	string	vitepress 的 srcDir 配置项
ignoreIndexMd	是否忽略每个目录下的 index.md 文件	boolean	false
cn	1 分钟内阅读的中文字数，阅读时间计算需要	number	300
en	1 分钟内阅读的英文字数，阅读时间计算需要	number	160
transformFile	自定义函数来返回额外的文件信息，最终存放到 fileInfo 里	Function	-

📖 Usage

获取插件分析后的数据：

1<script setup lang="ts">
2import { useData } from "vitepress";
3import type { DocAnalysis } from "vitepress-plugin-doc-analysis";
4
5const { theme } = useData();
6const { fileList, totalFileWords, eachFileWords, lastCommitTime }: DocAnalysis = theme.value;
7
8// 如果处在国际化环境下，vitepress 会将当前语言的 themeConfig 放到 theme 里，与原先的 theme 进行合并
9</script>
10
11<template></template>

如果不希望某个 Markdown 文档被插件分析，请在该文档 frontmatter 配置：

1---

2docAnalysis: false
3---

📚 Example

transformFile

通过 transformFile 配置项，可以自定义返回的文件信息。

1import type {} from "vitepress-plugin-doc-analysis";
2import DocAnalysis from "vitepress-plugin-doc-analysis";
3import { defineConfig } from "vitepress";
4import { statSync } from "node:fs";
5
6const docAnalysisOption = {
7  transformFile: (fileInfo: FilePathInfo) => {
8    // 获取文件的修改时间
9    const mtime = statSync(fileInfo.relativePath).mtime.toLocaleString();
10    return { mtime };
11  },
12};
13
14export default defineConfig({
15  vite: {
16    plugins: [DocAnalysis(docAnalysisOption)],
17  },
18});

验证：

1<script setup lang="ts">
2import { useData } from "vitepress";
3import type { DocAnalysis } from "vitepress-plugin-doc-analysis";
4
5const { theme } = useData();
6const { fileList }: DocAnalysis = theme.value;
7
8// 此时多出了 mtime
9console.log(fileList);
10</script>
11
12<template></template>

📘 TypeScript

🛠️ Options

1export interface DocAnalysisOption {
2  /**
3   * 忽略的文件/文件夹列表，支持正则表达式
4   *
5   * @default []
6   */
7  ignoreList?: Array<RegExp | string>;
8  /**
9   * 文章所在的目录，基于 .vitepress 目录层级添加，开头不需要有 /
10   *
11   * @default 'vitepress 的 srcDir 配置项'
12   */
13  path?: string;
14  /**
15   * 是否忽略每个目录下的 index.md 文件
16   *
17   * @default false
18   */
19  ignoreIndexMd?: boolean;
20  /**
21   * 1 分钟内阅读的中文字数
22   *
23   * @default 300
24   */
25  cn?: number;
26  /**
27   * 1 分钟内阅读的英文字数
28   *
29   * @default 160
30   */
31  en?: number;
32  /**
33   * 自定义函数来返回额外的文件信息，最终存放到 fileInfo 里
34   *
35   * @param filePath 文件路径信息
36   */
37  transformFile?: (filePath: FilePathInfo) => Record<string, any> | undefined;
38}

📖 Usage

1export interface DocAnalysis {
2  /**
3   * 文件路径列表
4   */
5  fileList: FilePathInfo[];
6  /**
7   * 文件总共字数
8   */
9  totalFileWords: string;
10  /**
11   * 文件信息列表
12   */
13  eachFileWords: FileInfo[];
14  /**
15   * git 上次 commit 时间
16   */
17  lastCommitTime: string;
18}
19
20export interface FileInfo {
21  /**
22   * 文件路径
23   */
24  fileInfo: FilePathInfo;
25  /**
26   * 字数
27   */
28  wordCount: number;
29  /**
30   * 阅读时间
31   */
32  readingTime: string;
33  /**
34   * 文件 frontmatter 数据
35   */
36  frontmatter: Record<string, any>;
37}
38
39export interface FilePathInfo {
40  /**
41   * 文件绝对路径
42   */
43  filePath: string;
44  /**
45   * 文件相对路径
46   */
47  relativePath: string;
48  /**
49   * 通过 transformFile 配置项得到的其他信息
50   */
51  [key: string]: any;
52}

🉑 License

MIT License © 2025 Teeker