1. 项目概述：一个为Markdown文档自动填充元数据的智能工具
如果你和我一样，长期在GitHub、博客或者文档项目里维护大量的Markdown文件，那你一定对重复填写文件头部的元数据（Front Matter）感到头疼。每次新建一个文档，都得手动敲入title、date、tags、categories这些字段，格式还不能错，繁琐且容易遗漏。今天要聊的这个开源项目sidyangx/mdac-filler，就是来解决这个痛点的。它本质上是一个命令行工具，能够自动为你指定的Markdown文件填充缺失的元数据，或者根据你的配置模板，批量生成结构化的文件头部信息。
这个工具的名字拆解一下很有意思：mdac我猜是 “Markdown Auto-Completion” 或类似含义的缩写，filler就是填充器。所以，它的核心使命非常明确——自动化、标准化你的Markdown元数据管理。它特别适合需要管理大量内容、追求Front Matter一致性的场景，比如静态博客生成器（Hugo, Jekyll, Hexo, VuePress, Docusaurus等）的用户、技术文档的维护者，或者任何希望提升Markdown文件管理效率的写作者。你不用再担心忘记写发布日期，或者给相似文章打上不同的标签，mdac-filler能帮你把这些琐事处理得井井有条。
2. 核心设计思路：基于配置与规则的自动化填充
mdac-filler的设计哲学不是简单地硬编码几个字段，而是提供了一套灵活可配的规则引擎。它的工作流程可以概括为“读取配置、分析文件、应用规则、写入结果”。这意味着它的行为完全由你定义，你可以让它变得很“聪明”。
2.1 核心工作流程解析
它的工作流程大致分为四步，理解这四步，你就能掌握它的精髓：
- 配置加载：工具启动后，首先会在当前目录或指定路径寻找配置文件（例如
.mdacfillerrc.yaml或mdac-filler.config.js）。这个配置文件定义了所有的填充规则、默认值以及文件匹配模式。没有配置，工具就不知道该如何行动。 - 文件扫描与解析：根据配置中指定的目录或通配符模式（如
./content/posts/*.md），工具会扫描所有目标Markdown文件。对于每个文件，它会解析现有的Front Matter（如果存在），并将其转换为一个内部的数据对象；如果不存在Front Matter，则创建一个空的数据对象。 - 规则应用：这是最核心的一步。工具会按照配置文件中定义的规则集，依次检查当前文件数据对象的每个字段。规则可能包括：“如果
date字段为空，则使用文件的创建时间或最后修改时间”；“如果title字段为空，则尝试从文件名的第一行或去除扩展名后的内容生成”；“为所有在./content/tech/目录下的文件自动添加tags: [‘技术’]”。规则会按照优先级顺序执行，后执行的规则可以覆盖先执行的结果。 - 回写文件：将所有规则应用完毕后，工具会将最终的数据对象，按照YAML或TOML等格式，重新生成为Front Matter，并写回到原Markdown文件的头部。它会确保格式的整洁与规范。
2.2 关键设计考量：为什么选择规则引擎？
你可能会问，为什么不直接写死几个默认值？这里就体现了工具设计者的深度思考。
- 灵活性：不同的项目、不同的文件夹可能有完全不同的元数据需求。一个个人博客的帖子可能需要
date,title,tags,draft；而一个项目文档可能需要version,sidebar_label,keywords。规则引擎允许你为不同的路径模式定义不同的规则集。 - 上下文感知：优秀的规则可以基于文件上下文智能填充。例如，根据文件路径深度自动生成
categories；根据文件内容中的关键词频率推荐tags；甚至读取Git历史来补充author或last_modified信息。虽然基础版本可能不包含复杂的NLP，但这个架构为未来扩展留下了空间。 - 幂等性与安全性：好的工具应该是“幂等”的，即多次运行产生相同的结果，且不会破坏已有数据。
mdac-filler的规则通常被设计为“仅填充空缺字段”或“在特定条件下覆盖”，而不是盲目清空重写。这保护了你手动精心填写的重要元数据。 - 与现有生态集成：它的输入输出是标准的Markdown with Front Matter，这意味着它能无缝接入任何支持该格式的静态站点生成器或文档系统，不需要修改你的构建流程。
3. 配置文件深度解析与实操定制
mdac-filler的强大与否，几乎完全取决于你的配置文件。一份好的配置，能让它从“自动填充器”进化成“智能内容助手”。我们以一个假设的YAML格式配置为例，进行深度拆解。
3.1 配置结构拆解
假设我们有一个.mdacfillerrc.yaml文件：
# .mdacfillerrc.yaml defaults: author: “你的名字” draft: false lang: “zh-CN” rules: - name: “基于文件时间的日期填充” match: “**/*.md” # 匹配所有md文件 actions: - if: “!frontmatter.date” set: date: “{{file.mtime | date(‘YYYY-MM-DD’)}}” - name: “从文件名提取标题” match: “**/*.md” actions: - if: “!frontmatter.title” set: title: “{{file.stem | titleCase}}” # file.stem是文件名（不含扩展名） - name: “技术博客标签” match: “content/posts/tech/**/*.md” actions: - set: tags: [“技术”] # 注意这里没有if条件，意味着总是执行，可能覆盖已有tags - if: “frontmatter.tags and ‘前端’ in frontmatter.tags” set: category: “Web开发” - name: “系列文章标识” match: “content/posts/series/*.md” actions: - set: series: “{{file.dirname | basename}}” # 使用目录名作为系列名 - if: “!frontmatter.order” set: order: “{{file.stem | slice(0,2) | int}}” # 假设文件名前两位是序号，如’01-xxx.md’ processors: - name: “slug生成器” match: “**/*.md” run: “{{frontmatter.title | slugify}}” set: “slug” - name: “摘要提取” match: “content/posts/**/*.md” run: “{{content | stripHtml | truncate(150)}}” # 从正文提取前150字纯文本 set: “excerpt”逐层解析：
defaults(默认值)：这是最基础的保障层。为所有匹配的文件设置一个全局的、最低优先级的默认值。通常用于那些几乎不变的信息，如author,lang。即使文件没有任何规则匹配，这些字段也能被填上。rules(规则集)：这是工具的大脑。每个规则包含：name：规则描述，便于调试和理解。match：一个 glob 模式，决定该规则对哪些文件生效。**/*.md表示递归匹配所有子目录下的.md文件。actions：规则的具体行为，是一个列表。每个action通常包含：if：条件表达式。例如!frontmatter.date表示 “如果 frontmatter 中不存在 date 字段或其为空”。这是实现“仅填充空缺”的关键。set：要设置的字段键值对。值可以是静态值，也可以是模板字符串。模板字符串{{…}}是灵魂所在，它能访问丰富的上下文变量，如file(文件信息)、frontmatter(现有元数据)、git(git信息)等，并通过过滤器（如date,titleCase,slugify）进行处理。
processors(处理器)：这是更高级、更强大的功能模块。你可以把它理解为一种特殊的规则，它的run属性是一个能产生复杂计算的模板表达式，并将结果set到指定字段。这非常适合用于生成slug（URL友好字符串）、从内容中自动提取excerpt（摘要）、或者计算阅读时间等衍生数据。
3.2 高级配置技巧与避坑指南
在实际配置中，有几个细节决定了它是“好用”还是“抓狂”。
规则的顺序至关重要：规则是按顺序执行的。你应该把最通用、最基础的规则（如填充日期、标题）放在前面，把更具体、可能覆盖前面结果的规则（如特定文件夹的标签）放在后面。在上面的例子中，“技术博客标签”规则会覆盖任何之前设置的
tags，因为它没有if条件限制。注意：对于可能冲突的字段（如
tags），使用if条件进行判断是更安全的选择，或者使用add动作（如果工具支持）来追加而非覆盖。模板表达式的威力与陷阱：
{{file.mtime | date(‘YYYY-MM-DD’)}}这样的表达式非常强大。但你需要清楚file.mtime是文件的最后修改时间，这在多次编辑后可能不是你想要的“发布日期”。更好的实践是优先使用file.ctime（创建时间），或者结合Git的首次提交时间。如果工具不支持，这就是一个需要留意的点。路径匹配的精确性：
match模式要尽可能精确，避免意外修改不该动的文件。例如，content/posts/**/*.md比**/*.md更好。你可以为drafts（草稿）和published（已发布）目录设置不同的规则。字段值的数据类型：在YAML中，
tags: [“技术”]是一个数组，draft: false是布尔值。确保你设置的值类型与你的静态站点生成器所期望的匹配。错误的类型可能导致构建错误或页面显示异常。备份与试运行：在第一次对大量文件运行前，务必先进行试运行。许多类似工具提供
--dry-run或--preview参数，只显示将要进行的更改而不实际写文件。如果没有这个功能，最稳妥的办法是先用git commit提交所有更改，或者复制一份文件到临时目录进行测试。
4. 完整实操流程：从零集成到批量处理
理论说得再多，不如动手操作一遍。下面我们以一个典型的 Hugo 博客项目为例，展示如何将mdac-filler集成到你的工作流中。
4.1 环境准备与工具安装
首先，你需要安装这个工具。由于它是开源项目，通常可以通过npm、pip或直接下载二进制文件安装。这里假设它是一个Node.js包。
# 在你的项目根目录下，通过npm安装为开发依赖 npm install -D sidyangx/mdac-filler # 或者全局安装 npm install -g sidyangx/mdac-filler安装后，可以通过npx mdac-filler --help或mdac-filler --help查看帮助命令，确认安装成功。
4.2 创建并定制配置文件
在你的博客项目根目录下，创建.mdacfillerrc.yaml文件。下面是一个为Hugo博客量身定制的、更复杂的配置示例：
# .mdacfillerrc.yaml - Hugo Blog Special defaults: author: “{{site.defaults.author}}” # 可以引用其他配置变量，如果工具支持 editor: “Visual Studio Code” format: “markdown” rules: # 规则1：核心元数据填充 - name: “填充标题和日期” match: “content/posts/**/*.md” actions: - if: “!frontmatter.title” set: title: “{{file.stem | replace(‘-’, ‘ ‘) | titleCase}}” - if: “!frontmatter.date” set: date: “{{file.ctime | date(‘2006-01-02T15:04:05-07:00’)}}” # Hugo的ISO8601格式 # 规则2：根据目录自动分类 - name: “自动分类” match: “content/posts/**/*.md” actions: - set: categories: “{{file.dirname | replace(‘content/posts/’, ‘‘) | split(‘/’) | first}}” # 解释：提取 ‘content/posts/tech/web’ 中的 ‘tech’ 作为分类 # 规则3：智能标签建议（基础版） - name: “标签建议” match: “content/posts/**/*.md” actions: - if: “frontmatter.categories == ‘tech’ and !frontmatter.tags” set: tags: [“编程”, “笔记”] - if: “frontmatter.categories == ‘life’ and !frontmatter.tags” set: tags: [“随笔”, “生活”] # 规则4：处理草稿 - name: “草稿标识” match: “content/drafts/**/*.md” actions: - set: draft: true processors: # 处理器1：生成slug（URL别名） - name: “hugo-slug” match: “content/**/*.md” run: “{{frontmatter.title | lower | replace(‘ ‘, ‘-‘) | replace(/[^\w-]/g, ‘‘)}}” set: “slug” # 处理器2：估算阅读时间 - name: “reading-time” match: “content/posts/**/*.md” run: “{{content | wordCount / 200 | round}}” # 假设200字/分钟 set: “readingTime”这个配置实现了：
- 从文件名生成美观的标题。
- 使用文件创建时间作为ISO8601格式的日期（Hugo偏好）。
- 根据文件所在子目录自动推断分类。
- 根据分类提供默认标签。
- 自动将
drafts目录下的文件标记为草稿。 - 自动生成URL友好的
slug。 - 根据正文字数估算阅读时间。
4.3 运行与验证
配置好后，就可以运行工具了。建议分步进行：
步骤一：预览模式（安全第一）
npx mdac-filler --dry-run --verbose这个命令会扫描所有匹配的文件，并详细打印出每个文件将会发生什么变化（例如：“将为空字段date设置值为 ‘2023-10-27T09:00:00+08:00’”），但不会真正修改文件。仔细检查输出，确认规则按预期工作。
步骤二：单文件测试
npx mdac-filler content/posts/my-new-article.md指定一个文件进行实际操作，然后打开该文件查看Front Matter是否被正确填充。这是验证配置最直接的方式。
步骤三：批量处理确认无误后，进行批量处理：
npx mdac-filler # 或者指定目录 npx mdac-filler content/posts/工具会安静地处理所有文件。处理完成后，使用git diff命令可以清晰地看到所有文件的变更，再次确认修改符合预期。
步骤四：集成到工作流为了让这个过程更自动化，你可以将其添加到package.json的scripts中：
{ “scripts”: { “prepublish”: “mdac-filler”, “newpost”: “hugo new posts/我的新文章.md && mdac-filler content/posts/我的新文章.md” } }这样，在构建前 (prepublish) 或创建新文章后 (newpost)，元数据都会被自动整理。
5. 常见问题、排查技巧与进阶玩法
即使配置再仔细，在实际使用中也可能遇到各种问题。下面是一些我踩过的坑和对应的解决方案。
5.1 常见问题速查表
| 问题现象 | 可能原因 | 排查与解决思路 |
|---|---|---|
| 运行后文件无任何变化 | 1. 配置文件路径或格式错误。 2. match模式未匹配到任何文件。3. 所有字段都已存在， if条件不满足。 | 1. 使用--config参数指定配置文件路径，或用--verbose查看加载的配置。2. 检查 match的 glob 模式，用简单的*.md测试。3. 检查 if条件逻辑，尝试临时去掉if看是否执行。 |
| 字段被意外覆盖或清空 | 规则顺序不当，或某条规则没有设置if条件，导致无条件set。 | 1. 检查规则顺序，将“无条件设置”的规则移到前面，或加上if条件。2. 使用 --dry-run模式观察每条规则的执行结果。 |
| 生成的日期、标题格式不对 | 模板表达式中的过滤器或格式字符串使用错误。 | 1. 查阅工具的文档，确认支持的变量和过滤器列表。 2. 在模板中直接输出原始变量值调试，如 {{file.mtime}}。 |
| 处理器（processor）未运行 | run表达式有语法错误，或set的字段已存在且未被覆盖。 | 1. 检查run表达式，确保引用的变量名正确。2. 处理器可能默认不覆盖已有字段，查看是否有相关配置选项。 |
| 运行速度很慢（文件多时） | 可能是每次处理都重新读取/解析整个配置文件，或者文件IO操作频繁。 | 1. 确保match模式尽可能精确，减少不必要的文件扫描。2. 如果工具支持，看看是否有缓存机制可以启用。 |
5.2 进阶玩法与扩展思路
当你熟练使用基础功能后，可以尝试这些进阶玩法，让工具发挥更大价值：
基于内容的智能标签：虽然基础版可能不支持，但你可以通过集成外部API或本地NLP库（如
node-nlp、jieba（中文））编写一个自定义脚本。脚本读取文件内容，提取关键词，然后通过工具提供的API或生成一个中间文件，再由mdac-filler读取并填入tags字段。这需要一定的编程能力，但效果显著。与Git信息联动：更高级的配置可以利用Git信息。例如，将
author字段设置为该文件的首次提交者 (git log --pretty=format:’%an’ --reverse path/to/file | head -1)。这需要工具能执行shell命令或内置Git支持。多环境配置：你可以创建多个配置文件，如
mdac-filler.config.dev.yaml和mdac-filler.config.prod.yaml。开发时使用宽松的规则，生产构建时使用严格的规则（例如，强制要求title和description非空）。通过环境变量或命令行参数切换配置。作为CI/CD的一部分：在GitHub Actions、GitLab CI等持续集成流程中，加入一个步骤，在合并请求（Pull Request）时自动运行
mdac-filler --dry-run，检查是否有新增的Markdown文件缺少必要的元数据，并给出提示或警告，确保仓库内容的规范性。
mdac-filler这类工具的价值在于，它将我们从重复、机械的元数据维护中解放出来，让我们能更专注于内容创作本身。它的配置虽然需要前期投入一些时间思考，但一旦设定好，就是一劳永逸的效率提升。记住，好的工具不是增加约束，而是通过合理的自动化，帮助你更好地遵守自己定下的规范。开始动手为你的Markdown仓库配置一个吧，第一次成功的批量处理完成后，那种整洁和统一带来的愉悦感，绝对值得。
