Vite 插件

Vitepress 是基于 Vite 进行搭建，因此可以编写 Vite 插件来辅助完成一些在无法在浏览器环境完成的动作，比如在 Vitepress 启动后，扫描文档目录下的 Markdown 文件，提取 frontmatter 的信息进行分析，或在渲染 Markdown 内容前，对其进行加工。

得益于 Vite 环境，Teek 内置了一些 Vite 插件来执行在 Node 环境才能完成的事情，这些插件分别为：

这些插件已经上传至 NPM 仓库，具体的使用说明可以前往 NPM 查看使用说明，或者访问 Github 仓库，每个插件下都有 README.md 文档介绍。

也可以在 Teek 的配置项中查看这些插件。

vitepress-plugin-permalink

Teek 使用 vitepress-plugin-permalink 来实现永久链接功能。

如果想要禁用该插件，进行如下配置：

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    permalink: false,
  },
});

Teek 默认扫描文档根目录下（srcDir）的所有 Markdown 文件，如果希望忽略某些目录，可进行如下配置：

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    permalinkOption: {
      ignore: ["目录名"], // 支持正则表达式
    },
  },
});

当希望只扫描指定的目录，可进行如下配置：

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    permalinkOption: {
      path: "guide", // 基于 .vitepress 目录层级添加，开头不需要有 /
    },
  },
});

国际化

vitepress-plugin-permalink 支持国际化功能，在生成 permalink 时，默认会给不同语言文档的 permalink 添加语言前缀。

假如存在一个 Markdown 文档 guide.md，frontmatter 内容如下：

yaml

---
title: guide
permalink: /guide
---

国际化目录结构如下；

docs/
├─ es/
│  ├─ guide.md
├─ guide.md

那么在生成 permalink 时，es 语言下的 guide.md 的 permalink 为 /es/guide。

配置项

permalinkOption 的详细配置项请看 Permalink 配置项。

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    permalinkOption: {},
  },
});

Teek 使用 vitepress-plugin-sidebar-resolve 来实现自动生成侧边栏功能。

在结构化目录中已经介绍了该插件使用的注意事项，如果想要禁用该插件，进行如下配置：

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    sidebar: false,
  },
});

国际化

在国际化的环境下，当把 root 语言（默认语言）的 Markdown 文件放到某个路径下时，vitepress-plugin-sidebar-resolve 无法感知到，因此请使用 localeRootDir 配置项告诉它，下面详细说明该场景。

Vitepress 支持的国际化文档目录如下：

docs/
├─ es/
│  ├─ foo.md
├─ fr/
│  ├─ foo.md
├─ foo.md

根目录下的 foo.md 是 root 语言（默认语言）的文档，当 Markdown 文件多起来时，根目录下文件显得很拥挤，那么可以将这些文档放到一个目录下，假设默认语言是 zh，则：

docs/
├─ es/
│  ├─ foo.md
├─ fr/
│  ├─ foo.md
├─ zh/
│  ├─ foo.md

但是 Vitepress 无法感知到 root 语言（默认语言）的文档已经放到 zh 目录下，它依然只扫描根目录的 Markdown 文件作为默认语言的文档，因此需要使用 Vitepress 提供的 rewrites 进行重定向，同时 vitepress-plugin-sidebar-resolve 插件无法感知文档进行了位移，因此需要配置 localeRootDir

import { defineConfig } from "vitepress";
import defineTeekConfig from "vitepress-theme-teek/config";

// Teek 主题配置
const teekConfig = defineTeekConfig({
  vitePlugins: {
    sidebarOption: {
      localeRootDir: "zh",
    },
  },
});

// Vitepress 配置
export default defineConfig({
  rewrites: {
    "zh/:rest*": ":rest*",
  },
});

侧边栏初始化格式

配置项 initItems 和 initItemsText 会影响侧边栏的生成格式，举个例子说明：

当 initItems 为 true，则最终结果为 sidebar: { "/guide": { items: [], collapsed }}
- 当 initItemsText 为 true，则最终结果为 sidebar: { "/guide": { text: "guide", items: [], collapsed }}
- 当 initItemsText 为 false，则最终结果为 sidebar: { "/guide": { items: [] }}
当 initItems 为 false，则最终结果为 sidebar: { "/guide": [] }

配置项

sidebarOption 的详细配置项请看 SideBar 配置项。

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    sidebarOption: {},
  },
});

vitepress-plugin-md-h1

Teek 使用 vitepress-plugin-md-h1 来给文章页生成一级标题（假如 Markdown 文档没有设置过一级标题）。

一级标题获取顺序：frontmatter.title > 文件名

提示

只在页面加载 Markdown 内容时生成一级标题，并不会真正修改 Markdown 文档内容。

假设一个文档 install.md 的 frontmatter 内容如下：

yaml

---
title: guide
---

在页面访问该文档时，页面自动生成一级标题 guide，当把 frontmatter.title 去掉后，页面的一级标题变为 install。

如果想要禁用该插件，进行如下配置：

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    mdH1: false,
  },
});

配置项

mdH1Option 的详细配置项请看 MdH1Option 配置项。

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    mdH1Option: {},
  },
});

vitepress-plugin-catalogue

vitepress-plugin-catalogue 插件会将所有 formatter.catalogue 为 true 的文档信息挂载到 themeConfig.catalogues 中，Teek 使用该数据来生成目录页。

该插件与 Teek 强绑定，无法像上面的组件一样，通过 vitePlugins.catalogue = false 来禁用。

如果想要禁用该插件，只能通过禁用 Teek 主题来实现，配置如下：

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  tkTheme: false, // 禁用 Teek 主题
});

如果某个 markdown 文档不想被纳入目录里，则：

yaml

---
inCatalogue: false
---

配置项

catalogueOption 的详细配置项请看 Catalogue 配置项。

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    catalogueOption: {},
  },
});

vitepress-plugin-doc-analysis

Teek 使用 vitepress-plugin-doc-analysis 来实现站点信息和文章页信息功能。

vitepress-plugin-doc-analysis 在 Vitepress 启动后，扫描所有的 Markdown 文档，然后统计文章数量，文章字数等，最终将分析后的数据挂载到 themeConfig.docAnalysisInfo 中。

在首页看到的站点信息、文章页看到的文章字数、预计阅读时间等，都是使用 themeConfig.docAnalysisInfo 的数据来构成。

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

yaml

---
docAnalysis: false
---

如果想要禁用该插件，进行如下配置：

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    docAnalysis: false,
  },
});

关于文章的预计阅读时间的计算，该插件默认 1 分钟内阅读的中文字数为 300，1 分钟内阅读的英文字数为 160，如果认为不合理，可以对其进行修改：

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    docAnalysisOption: {
      cn: 400,
      en: 200,
    },
  },
});

国际化

当处于国际化环境下，插件将不同语言的数据挂载到 locales.[lang].themeConfig.docAnalysisInfo。

配置项

docAnalysisOption 的详细配置项请看 DocAnalysis 配置项。

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    docAnalysisOption: {},
  },
});

vitepress-plugin-file-content-loader

Teek 使用 vitepress-plugin-file-content-loader 来构建首页的文章列表和归档页数据，并挂载到 themeConfig.posts 中。

该插件本质上将 Vitepress 官网的构建时数据加载功能转为插件，因此具体的介绍说明请前往 Vitepress 官网阅读。

为什么设计为插件？

构建时数据加载功能是在访问网站的时候开始执行，如果使用该功能扫描了大量的 Markdown 文档，那么会导致第一次进入页面卡顿，因此基于该功能实现了插件，在项目启动过程完成数据的加载。

该插件与 Teek 强绑定，如果想要禁用该插件，只能通过禁用 Teek 主题来实现，配置如下：

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  tkTheme: false, // 禁用 Teek 主题
});

国际化

当处于国际化环境下，插件将不同语言的数据挂载到 themeConfig.posts.locales.[lang] 下。

配置项

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    fileContentLoaderIgnore: {}, // fileContentLoader 插件扫描 markdown 文档时，指定忽略路径，格式为 glob 表达式，如 test/**
  },
});

vitepress-plugin-auto-frontmatter

Teek 使用 vitepress-plugin-auto-frontmatter 自动给 Markdown 文档添加 frontmatter。

该插件会直接修改 Markdown 文档的 frontmatter，因此为了安全性考虑，默认是关闭的，如果希望开启，进行如下配置：

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatter: true,
  },
});

如果开启了该插件，那么 Teek 将会对所有 Markdown 文档的 frontmatter 添加如下格式：

yaml

---
title: getting
date: 2025-03-03 00:45:16
permalink: /pages/eb8f2f
categories:
  - guide
---

title 为文章的标题
date 为文章的创建时间
permalink 为文章的永久链接，采用随机数确保唯一
categories 为文章的分类，根据目录层级获取

提示

Teek 则不会修改已经存在的数据，判断的规则是比较 key，不比较 value。

如果需要拓展自定义 frontmatter，让 Teek 在生成 frontmatter 的时候额外添加其他数据，请使用 transform 配置项，具体使用请看 vitepress-plugin-auto-frontmatter 的 Example 2 和 Example 3。

配置项

autoFrontmatterOption 的详细配置项请看 AutoFrontmatter 配置项。

Teek 在 vitepress-plugin-auto-frontmatter 的配置项基础上额外添加两个配置项：

permalinkPrefix：自动生成 permalink 的固定前缀，如 pages、pages/demo，默认为 pages
categories：是否自动生成 categories

import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatterOption: {
      permalinkPrefix: "pages", // 自动生成 permalink 的固定前缀，如 pages、pages/demo，默认为 pages
      categories: true, // 是否自动生成 categories
      // ...
    },
  },
});

主题配置

插件

安装-faq

本地安装升级方法

指南

简介

使用

相关

开发

配置

主题配置

主题开发

常见问题

生态

介绍

基础配置

进阶玩法

其它站点

简介

写作

自定义

实验性功能

配置和API参考

Vite 插件 ​

vitepress-plugin-permalink ​

国际化 ​

配置项 ​

vitepress-plugin-sidebar-resolve ​

国际化 ​

侧边栏初始化格式 ​

配置项 ​

vitepress-plugin-md-h1 ​

配置项 ​

vitepress-plugin-catalogue ​

配置项 ​

vitepress-plugin-doc-analysis ​

国际化 ​

配置项 ​

vitepress-plugin-file-content-loader ​

国际化 ​

配置项 ​

vitepress-plugin-auto-frontmatter ​

配置项 ​

Vite 插件

vitepress-plugin-permalink

国际化

配置项

vitepress-plugin-sidebar-resolve

国际化

侧边栏初始化格式

配置项

vitepress-plugin-md-h1

配置项

vitepress-plugin-catalogue

配置项

vitepress-plugin-doc-analysis

国际化

配置项

vitepress-plugin-file-content-loader

国际化

配置项

vitepress-plugin-auto-frontmatter

配置项