vitepress-plugin-setfrontmatter

github地址

vitepress-plugin-setfrontmatter

这是一个适用于vitepress的 Vite 插件，vitepress启动时，插件会给指定的 markdown 自动生成frontmatter。

vitepress插件

✨ 特性

• ✨ 自动为Markdown文件添加缺失的frontmatter字段（标题、日期、永久链接等）
• 🔄 支持自定义frontmatter转换函数
• 📁 支持自动生成基于文件路径的分类信息
• 🗑️ 支持删除指定的frontmatter字段
• 🌐 兼容VitePress的国际化配置

安装

安装 vitepress-plugin-setfrontmatter 插件

npm

npm install vitepress-plugin-setfrontmatter --save-dev

yarn

yarn add vitepress-plugin-setfrontmatter -D

pnpm

pnpm i vitepress-plugin-setfrontmatter -D

使用方法

在VitePress配置文件中引入并使用插件

.vitepress/config.ts

import { defineConfig } from 'vitepress'
import AutoFrontmatter from 'vitepress-plugin-setfrontmatter'

export default defineConfig({
  vite: {
    plugins: [
      AutoFrontmatter ({
        pattern: '**/*.md',
        globOptions: { ignore: [""] } //忽略的文件或目录
        permalinkPrefix: 'pages', // 永久链接前缀，如设置为"/pages/"，生成的permalink为"/pages/xxxx",不设置则不会生成
        categories: true // 是否启用自动添加frontmatter.categories功能
      })
    ]
  }
})

typescript

export interface AutoFrontmatterOption {
  /**
   * 扫描的文件路径表达式，为 global 表达式
   */
  // 处理所有Markdown文件 pattern: "**/*.md"
  // 只处理docs目录下的Markdown文件 pattern: 'docs/**/*.md'
  // 处理多个目录 pattern: ['docs/**/*.md', 'blog/**/*.md']
  pattern?: string | string[];
  /**
   * tinyglobby 的配置项
   * 插件默认已经忽略 node_modules 和 dist 目录的所有文件
   */
  globOptions?: GlobOptions;
  /**
   * permalink 前缀，设置生成的永久链接前缀。如果设置了此选项，插件会为每个Markdown文件生成一个唯一的永久链接。例如设置为 "/pages/"，则生成的 permalink 为 "/pages/xxxx"，不设置则不会生成
   */
  permalinkPrefix?: string;
  /**
    * 是否启用自动添加 frontmatter.categories 功能，默认为 true   
  */
  categories?: boolean;
  /**
   * 要从 frontmatter 中删除的键名
   * 下面配置的coverImg为false并且key存在，则删除该 key，默认为 "coverImg"
   */
  key?: string;
  /**
   * 是否启用自动添加 frontmatter.coverImg 功能，默认为 false
   */
  coverImg?: boolean | undefined;
  /**
   * 转换处理好的 frontmatter，该函数需要返回一个新的 frontmatter 或只返回 undefined，如果返回 {}，则清空 MD 文件本身存在的 frontmatter
   */
  transform?: (frontmatter: Record<string, any>, fileInfo: FileInfo) => Record<string, any> | void;
}

export interface FileInfo {
  /**
   * 文件绝对路径
   */
  filePath: string;
  /**
   * 文件相对路径
   */
  relativePath: string;
}

说明：该插件仅限项目启动时生效。

• 插件默认忽略 frontmatter 中 layout: home 和 ["node_modules", "dist"] 目录下的文件，且只扫描 Markdown 文档。
• 插件默认给 Markdown 文件生成 title 和 date 两个属性，其中 title 为文件名（支持带序号的文件名，如 01.xx.md），date 为文件的创建日期，permalinkPrefix和categories选项都是可选的，如果想拓展 frontmatter 的内容，则使用 transform 函数。

transform详细说明

自定义转换frontmatter的函数。该函数接收两个参数：当前的frontmatter对象和文件信息对象。

transform: (frontmatter) => {
  // 添加自定义字段
  return {
    ...frontmatter,
    author: 'Your Name',
    tags: ['vitepress', 'plugin']
  }
}

如果函数返回一个对象，该对象将作为新的frontmatter；如果返回undefined，则使用原frontmatter；如果返回空对象{}，则清空原有frontmatter，下面展示了一个例子，根据文件路径添加标签

import { defineConfig } from 'vitepress'
import AutoFrontmatter from 'vitepress-plugin-setfrontmatter'

export default defineConfig({
  vite: {
    plugins: [
      AutoFrontmatter ({
        pattern: '**/*.md',
        transform: (frontmatter, fileInfo) => {
          // 根据文件路径添加标签
          const tags = []
          if (fileInfo.relativePath.includes('vue')) {
            tags.push('vue')
          }
          if (fileInfo.relativePath.includes('react')) {
            tags.push('react')
          }
          
          return {
            ...frontmatter,
            tags,
            lastUpdated: new Date().toISOString()
          }
        }
      })
    ]
  }
})

配置选项

选项	类型	默认值	描述
pattern	string | string[]	-	扫描的文件路径表达式，使用glob语法
globOptions	GlobOptions	-	tinyglobby的配置项，插件默认已忽略node_modules和dist目录
permalinkPrefix	string	-	永久链接前缀，如设置为"/pages/"，生成的permalink为"/pages/xxxx"，不设置则不会生成永久链接
categories	boolean	false	是否启用自动添加frontmatter.categories功能
key	string	"coverImg"	要从frontmatter中删除的键名，coverImg配置为false并且key存在于frontmatter生效
coverImg	boolean	false	是否启用自动添加frontmatter.coverImg功能
transform	Function	-	自定义转换frontmatter的函数

工作原理

插件会在VitePress构建过程中扫描指定的Markdown文件，并执行以下操作：

1. 读取文件内容并解析现有的frontmatter
2. 如果缺少标题，则根据文件名自动生成
3. 如果缺少日期，则使用文件创建时间
4. 如果设置了permalinkPrefix，则生成唯一的永久链接
5. 如果启用了categories功能，则根据文件路径生成分类信息
6. 如果提供了transform函数，则使用该函数进一步处理frontmatter
7. 将处理后的frontmatter写回文件