vitepress-plugin-setfrontmatter

一个用于自动为VitePress项目中的Markdown文件生成和管理frontmatter的Vite插件。

功能特点

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

安装

安装命令

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

# yarn
yarn add vitepress-plugin-setfrontmatter -D

# pnpm
pnpm add vitepress-plugin-setfrontmatter -D

使用方法

基本配置

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

// .vitepress/config.js 或 .vitepress/config.ts
import { defineConfig } from 'vitepress'
import VitePluginVitePressAutoFrontmatter from 'vitepress-plugin-setfrontmatter'

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

配置选项

| 选项 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | 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的函数 |

详细说明

pattern

指定需要处理的Markdown文件路径，支持glob表达式。可以是单个字符串或字符串数组。

// 处理所有Markdown文件
pattern: '**/*.md'

// 只处理docs目录下的Markdown文件
pattern: 'docs/**/*.md'

// 处理多个目录
pattern: ['docs/**/*.md', 'blog/**/*.md']

globOptions

tinyglobby的配置选项，可以进一步控制文件匹配行为。插件默认已忽略node_modules和dist目录。

globOptions: {
  ignore: ['**/drafts/**'], // 忽略drafts目录下的所有文件
  expandDirectories: true
}

permalinkPrefix

设置生成的永久链接前缀。如果设置了此选项，插件会为每个Markdown文件生成一个唯一的永久链接。

// 生成的永久链接形如: /posts/a1b2c3
permalinkPrefix: 'posts'

categories

是否启用自动添加分类功能。启用后，插件会根据文件路径自动生成分类信息。

// 启用自动分类功能
categories: true

例如，对于路径为docs/frontend/vue/guide.md的文件，生成的分类将是['frontend', 'vue']。

key

指定要从frontmatter中删除的键名。当coverImg配置为false且该键存在于frontmatter中时，插件会删除该键。

// 删除frontmatter中的'banner'字段
key: 'banner'

coverImg

是否启用自动添加coverImg功能。默认为false。

// 启用自动添加coverImg功能
coverImg: true

transform

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

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

如果函数返回一个对象，该对象将作为新的frontmatter；如果返回undefined，则使用原frontmatter；如果返回空对象{}，则清空原有frontmatter。

文件信息对象

transform函数的第二个参数是文件信息对象，包含以下属性：

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

使用示例

基本用法

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

export default defineConfig({
  vite: {
    plugins: [
      VitePluginVitePressAutoFrontmatter({
        pattern: '**/*.md',
        permalinkPrefix: 'pages'
      })
    ]
  }
})

自定义转换函数

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

export default defineConfig({
  vite: {
    plugins: [
      VitePluginVitePressAutoFrontmatter({
        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()
          }
        }
      })
    ]
  }
})

自动生成分类

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

export default defineConfig({
  vite: {
    plugins: [
      VitePluginVitePressAutoFrontmatter({
        pattern: '**/*.md',
        categories: true,
        globOptions: {
          ignore: ['**/private/**'] // 忽略private目录下的文件
        }
      })
    ]
  }
})

工作原理

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

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

贡献指南

欢迎对本项目提出改进建议或贡献代码。请遵循以下步骤：

1. Fork本仓库
2. 创建您的特性分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开Pull Request

相关链接

• GitHub仓库
• 问题反馈
• VitePress官方文档
• 博客地址