开发工具CLI前端【免费下载链接】metalsmithAn extremely simple, pluggable static site generator for Node.js项目地址https://gitcode.com/gh_mirrors/me/metalsmith点击查看免费下载导读本文以 Metalsmith 官方测试夹具 test/fixtures/read-frontmatter/src/index.md 中的---\nthing: true\n---为切入点深入剖析 Metalsmith 静态站点生成器中 Front Matter前端元数据的完整解析链路——从源文件读取、YAML 解析、元数据挂载到文件对象File Object的构建过程。读完本文你将掌握如何通过 YAML 在 Markdown 源文件中声明页面元数据理解frontmatter()API 的开关与选项配置并能利用 gray-matter 引擎扩展自定义元数据语言如 TOML。什么是 Front MatterMetalsmith 中元数据的入口在 Metalsmith 的构建模型中任何位于源目录默认src中的文本文件都可以携带 YAML Front Matter——即文件开头用---分隔符包裹的一段 YAML 元数据。这是一切内容型工作流的核心文章标题、发布日期、标签、布局模板名等结构化信息都可以写在这里与正文分离。以关联文档 test/fixtures/read-frontmatter/src/index.md 为最简实例其完整内容如下--- thing: true ---这是一个仅含单个布尔字段thing: true的元数据块首尾各一行---作为 YAML 分隔符中间是 YAML 键值对。Metalsmith 读取该文件后会把thing: true解析为 JavaScript 布尔值true并作为该文件对象File Object的属性挂载同时contents属性保留文件正文此处正文为空。仓库 README 中给出了更典型的带正文示例见 README.md--- title: A Catchy Title date: 2024-01-01 --- An informative article.上述文件经解析后得到的文件对象为{ path/to/my-file.md: { title: A Catchy Title, date: new Date(2024, 1, 1), contents: Buffer.from(An informative article), stats: fs.Stats } }可以看到Front Matter 中的所有 YAML 字段都被“扁平化”挂载到文件对象的顶层与contents、stats、mode等内置属性并列。这正是后续所有插件操作页面数据的统一入口。解析链路从磁盘文件到文件对象Metalsmith 的构建过程分三步读取源目录文件、依次执行插件、写出构建产物见 README.md。Front Matter 的解析发生在第一步——Metalsmith#read/Metalsmith#readFile中。从源码看核心调用链为lib/index.js 与 lib/index.jsread()递归遍历源目录readdir将非静态文件批量交给readFile()批量读取受concurrency()配置的并发数控制readFile()使用fs.promises.stat与fs.promises.readFile并行读取文件内容若frontmatter开关为真且文件内容是 UTF-8 文本通过is-utf8判断则调用this.matter.parse(buffer)执行 Front Matter 解析解析结果与文件mode八进制权限字符串和statsfs.Stats实例一起构成最终的文件对象。其中第 3 步的关键实现位于 lib/matter.js 的Matter.prototype.parseMatter.prototype.parse function (fileBuffer) { const result {} const parsed matter(fileBuffer.toString(), this[_options]) Object.assign(result, parsed.data) // ... excerpt 处理可选 result.contents Buffer.from(parsed.content) return result }parse的职责清晰调用 gray-matter 的matter()函数解析文本将parsed.dataYAML 解析出的元数据对象通过Object.assign合并进结果再把正文部分parsed.content重新包装为Buffer存入contents。也就是说Front Matter 与正文的分离在读取阶段就已完成。frontmatter() API开关与选项配置Metalsmith 实例在构造时默认开启 Front Matter 解析this.frontmatter(true)见 lib/index.js。你可以通过frontmatter()方法获取当前状态或传入布尔值/选项对象进行配置。完全关闭解析在Metalsmith.prototype.frontmatter的实现中lib/index.js传入false会直接关闭解析const m Metalsmith(fixture(read-frontmatter)) m.frontmatter(false) m.read(function (err, files) { // files[index.md].thing 为 undefined })对应的测试用例位于 test/index.js当frontmatter(false)时index.md中原本存在的thing: true不会被解析文件对象上不存在thing属性。此时readFile走的是ret.contents buffer分支lib/index.js文件内容原样保留不做任何元数据提取。值得注意的是关闭解析后contents会包含完整的---分隔符原文这在需要原样搬运文件例如构建纯静态资源时很有用但若后续仍想以模板渲染 Markdown则需自行处理分隔符。传入 gray-matter 选项对象frontmatter()也可以接收一个选项对象其类型定义见 types/index.d.ts 的MatterOptions接口。Metalsmith 内部把该对象直接透传给 gray-matter 解析器lib/index.js 调用this.matter.options(frontmatter)。lib/matter.js中定义的默认选项为lib/matter.jsconst defaultOptions { excerpt: false, excerpt_separator: ---, language: yaml, delimiters: --- }各选项含义如下选项默认值作用excerptfalse是否从正文中提取摘要excerpt开启后摘要会作为文件对象的excerpt属性存在并从contents中剥离excerpt_separator---正文中用于截断摘要的分隔符字符串languageyamlFront Matter 使用的标记语言gray-matter 内置yaml、json、toml等delimiters---Front Matter 的分隔符支持字符串或[open, close]字符串数组形式engines无自定义解析引擎用于扩展 gray-matter 未内置的语言JSON 格式的 Front Matter一个文件两种语言除了 YAMLgray-matter 还支持 JSON 格式的元数据块。仓库中 test/fixtures/read-frontmatter/src/json.md 展示了这一点--- {json: true} ---注意此处分隔符仍然是---只是中间内容从 YAML 键值对变成了 JSON 对象字面量。测试用例test/index.js验证了解析结果Metalsmith(fixture(read-frontmatter)) .use((fileObj) { files fileObj }) .process(function (err) { assert.strictEqual(files[json.md].json, true) done() })即json.md文件对象上会存在json: true属性。gray-matter 会根据内容形态自动识别 JSON 语法因此你可以在同一源目录中混用 YAML 与 JSON 两种 Front Matter 写法。自定义语言与分隔符TOML 示例实战gray-matter 默认支持的语言有限但 Metalsmith 通过engines选项开放了扩展能力。仓库中的另一个测试夹具 test/fixtures/read-frontmatter-custom/src/index.md 展示了 TOML 场景~~~ thing true ~~~ An excerpt ~~~它同时改变了三件事分隔符从---变为~~~、语言从yaml变为toml、并启用了excerpt提取。对应的测试配置test/index.jsconst toml require(toml) Metalsmith(fixture(read-frontmatter-custom)) .frontmatter({ engines: { toml: toml.parse.bind(toml) }, language: toml, excerpt_separator: ~~~, delimiters: ~~~, excerpt: true }) .use((fileObj) { files fileObj }) .process(function (err) { assert.strictEqual(files[index.md].thing, true) assert.strictEqual(files[index.md].excerpt.trim(), An excerpt) done() })测试断言了两个结果thing被解析为true且excerpt属性被截取为An excerpt。这一配置组合在实际项目中非常实用——例如团队规范要求使用 TOML 写配置时可以无缝切换。excerpt摘要提取原理当excerpt: true时Matter.prototype.parse会执行摘要提取逻辑lib/matter.jsif (this[_options].excerpt parsed.excerpt) { result.excerpt parsed.excerpt.trim() // 从 contents 中剥离摘要与分隔符 parsed.content parsed.content.replace( new RegExp(^${result.excerpt}\\s*${this[_options].excerpt_separator}\\s*), ) }工作过程分两步gray-matter 依据excerpt_separator在正文中寻找分隔行将分隔行之前的内容识别为摘要Metalsmith 将摘要存入result.excerpt并从contents中移除摘要与分隔符本身确保正文纯净不会在渲染时重复输出。这正是read-frontmatter-customfixture 中An excerpt行之后又以~~~收尾的原因——它充当正文内的摘要分隔符。这一机制让“列表页显示摘要、详情页显示全文”的博客模式变得非常简单。无效 Front Matter 的容错处理如果源文件中的 Front Matter 语法有误Metalsmith 不会静默吞掉错误。从 lib/index.js 可以看到matter.parse抛出异常时会被捕获并包装为带code: invalid_frontmatter的 Errortry { ret this.matter.parse(buffer) } catch { const err new Error(Invalid frontmatter in the file at: file) err.code invalid_frontmatter return Promise.reject(err) }对应的无效夹具 test/fixtures/read-invalid-frontmatter/src/index.md 内容为--- - a b: test --- Body这是一个缩进错乱的 YAML 序列列表项后错误地缩进了键值对无法被 YAML 解析器接受。遇到此类文件时构建会以invalid_frontmatter错误终止便于你快速定位问题文件。因此在实际项目中建议在写入 Front Matter 时严格遵循 YAML 缩进规范并在 CI 中尽早暴露此类错误。与文件模式、静态文件的协同Front Matter 解析只是read阶段的一部分。对每个文件Metalsmith 还会同时维护两个与解析无关的属性mode文件的 Unix 权限位八进制字符串读取自fs.Stats写入时用于还原文件权限statsfs.Stats实例可被插件用于判断文件大小、修改时间等。此外被ignore或match规则命中的静态文件如CNAME、图片、样式表不会走 Front Matter 解析路径而是直接以contents: Buffer.from(p)内容即其路径字符串见 lib/index.js的形态进入文件集合后续由插件如 test/fixtures/static/src 场景按需处理。这一设计保证了二进制与非文本资源不会被误解析。从测试夹具到生产实践三步上手将上述机制落地到你的 Metalsmith 项目中可以按三步走第一步在源文件中声明元数据。在src目录下的 Markdown 文件开头书写 YAML Front Matter例如--- title: 我的第一篇文章 date: 2024-01-01 tags: [metalsmith, frontmatter] layout: post.hbs --- 正文内容……第二步按需配置 frontmatter()。在metalsmith.json或构建脚本中声明{ source: src, destination: build, frontmatter: { excerpt: true, excerpt_separator: --- } }metalsmith.json可识别的顶层选项包括source、destination、concurrency、metadata、clean和frontmatter见 README.md。也可以在脚本中链式调用metalsmith.frontmatter({ excerpt: true })。第三步在插件或模板中消费元数据。读取阶段完成后插件拿到的每个文件对象都已包含 Front Matter 字段。例如 draft 插件可依据draft: true过滤未发布的文章参考 examples/drafts-plugin/index.js布局模板则可通过title、date、tags等字段渲染页面。至此一条从 YAML 元数据到最终 HTML 的完整流水线便贯通了。小结Metalsmith 的 Front Matter 机制虽然入口只是一个两行---包裹的 YAML 块如test/fixtures/read-frontmatter/src/index.md所示但其背后串联起了完整的读取、解析、元数据挂载与容错体系frontmatter()API 控制开关与 gray-matter 选项Matter.parse负责分离元数据与正文excerpt机制支撑摘要场景engines扩展支持 TOML 等自定义语言而invalid_frontmatter错误码保证了错误可定位。掌握这一层机制你就能更自如地驾驭内容元数据驱动的静态站点构建。赞分享开发工具CLI前端【免费下载链接】metalsmithAn extremely simple, pluggable static site generator for Node.js项目地址https://gitcode.com/gh_mirrors/me/metalsmith点击查看免费下载相关推荐MarkText前端元数据使用YAML front matter的完整教程MarkText前端元数据使用YAML front matter的完整教程 MarkText作为一款优雅的Markdown编辑器提供了强大的YAML fro桌面应用富文本Forge Code 技能机制详解SKILL.md 的 YAML Front Matter 元数据规范与解析原理Forge Code 技能机制详解SKILL.md 的 YAML Front Matter 元数据规范与解析原理 本篇文章以 Forge Codeforge人工智能AI Agent代码智能体AI 应用CLI开发工具Markdig YAML Front Matter解析元数据管理的完整指南Markdig YAML Front Matter解析元数据管理的完整指南 YAML Front Matter是Markdown文档中用于存储元数据的强大工具开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/15 15:24:22 · 阅读 1.2k Metalsmith 前端元数据（Front Matter）解析机制详解：从 YAML 元数据到文件对象
开发工具CLI前端【免费下载链接】metalsmithAn extremely simple, pluggable static site generator for Node.js项目地址https://gitcode.com/gh_mirrors/me/metalsmith点击查看免费下载导读本文以 Metalsmith 官方测试夹具 test/fixtures/read-frontmatter/src/index.md 中的---\nthing: true\n---为切入点深入剖析 Metalsmith 静态站点生成器中 Front Matter前端元数据的完整解析链路——从源文件读取、YAML 解析、元数据挂载到文件对象File Object的构建过程。读完本文你将掌握如何通过 YAML 在 Markdown 源文件中声明页面元数据理解frontmatter()API 的开关与选项配置并能利用 gray-matter 引擎扩展自定义元数据语言如 TOML。什么是 Front MatterMetalsmith 中元数据的入口在 Metalsmith 的构建模型中任何位于源目录默认src中的文本文件都可以携带 YAML Front Matter——即文件开头用---分隔符包裹的一段 YAML 元数据。这是一切内容型工作流的核心文章标题、发布日期、标签、布局模板名等结构化信息都可以写在这里与正文分离。以关联文档 test/fixtures/read-frontmatter/src/index.md 为最简实例其完整内容如下--- thing: true ---这是一个仅含单个布尔字段thing: true的元数据块首尾各一行---作为 YAML 分隔符中间是 YAML 键值对。Metalsmith 读取该文件后会把thing: true解析为 JavaScript 布尔值true并作为该文件对象File Object的属性挂载同时contents属性保留文件正文此处正文为空。仓库 README 中给出了更典型的带正文示例见 README.md--- title: A Catchy Title date: 2024-01-01 --- An informative article.上述文件经解析后得到的文件对象为{ path/to/my-file.md: { title: A Catchy Title, date: new Date(2024, 1, 1), contents: Buffer.from(An informative article), stats: fs.Stats } }可以看到Front Matter 中的所有 YAML 字段都被“扁平化”挂载到文件对象的顶层与contents、stats、mode等内置属性并列。这正是后续所有插件操作页面数据的统一入口。解析链路从磁盘文件到文件对象Metalsmith 的构建过程分三步读取源目录文件、依次执行插件、写出构建产物见 README.md。Front Matter 的解析发生在第一步——Metalsmith#read/Metalsmith#readFile中。从源码看核心调用链为lib/index.js 与 lib/index.jsread()递归遍历源目录readdir将非静态文件批量交给readFile()批量读取受concurrency()配置的并发数控制readFile()使用fs.promises.stat与fs.promises.readFile并行读取文件内容若frontmatter开关为真且文件内容是 UTF-8 文本通过is-utf8判断则调用this.matter.parse(buffer)执行 Front Matter 解析解析结果与文件mode八进制权限字符串和statsfs.Stats实例一起构成最终的文件对象。其中第 3 步的关键实现位于 lib/matter.js 的Matter.prototype.parseMatter.prototype.parse function (fileBuffer) { const result {} const parsed matter(fileBuffer.toString(), this[_options]) Object.assign(result, parsed.data) // ... excerpt 处理可选 result.contents Buffer.from(parsed.content) return result }parse的职责清晰调用 gray-matter 的matter()函数解析文本将parsed.dataYAML 解析出的元数据对象通过Object.assign合并进结果再把正文部分parsed.content重新包装为Buffer存入contents。也就是说Front Matter 与正文的分离在读取阶段就已完成。frontmatter() API开关与选项配置Metalsmith 实例在构造时默认开启 Front Matter 解析this.frontmatter(true)见 lib/index.js。你可以通过frontmatter()方法获取当前状态或传入布尔值/选项对象进行配置。完全关闭解析在Metalsmith.prototype.frontmatter的实现中lib/index.js传入false会直接关闭解析const m Metalsmith(fixture(read-frontmatter)) m.frontmatter(false) m.read(function (err, files) { // files[index.md].thing 为 undefined })对应的测试用例位于 test/index.js当frontmatter(false)时index.md中原本存在的thing: true不会被解析文件对象上不存在thing属性。此时readFile走的是ret.contents buffer分支lib/index.js文件内容原样保留不做任何元数据提取。值得注意的是关闭解析后contents会包含完整的---分隔符原文这在需要原样搬运文件例如构建纯静态资源时很有用但若后续仍想以模板渲染 Markdown则需自行处理分隔符。传入 gray-matter 选项对象frontmatter()也可以接收一个选项对象其类型定义见 types/index.d.ts 的MatterOptions接口。Metalsmith 内部把该对象直接透传给 gray-matter 解析器lib/index.js 调用this.matter.options(frontmatter)。lib/matter.js中定义的默认选项为lib/matter.jsconst defaultOptions { excerpt: false, excerpt_separator: ---, language: yaml, delimiters: --- }各选项含义如下选项默认值作用excerptfalse是否从正文中提取摘要excerpt开启后摘要会作为文件对象的excerpt属性存在并从contents中剥离excerpt_separator---正文中用于截断摘要的分隔符字符串languageyamlFront Matter 使用的标记语言gray-matter 内置yaml、json、toml等delimiters---Front Matter 的分隔符支持字符串或[open, close]字符串数组形式engines无自定义解析引擎用于扩展 gray-matter 未内置的语言JSON 格式的 Front Matter一个文件两种语言除了 YAMLgray-matter 还支持 JSON 格式的元数据块。仓库中 test/fixtures/read-frontmatter/src/json.md 展示了这一点--- {json: true} ---注意此处分隔符仍然是---只是中间内容从 YAML 键值对变成了 JSON 对象字面量。测试用例test/index.js验证了解析结果Metalsmith(fixture(read-frontmatter)) .use((fileObj) { files fileObj }) .process(function (err) { assert.strictEqual(files[json.md].json, true) done() })即json.md文件对象上会存在json: true属性。gray-matter 会根据内容形态自动识别 JSON 语法因此你可以在同一源目录中混用 YAML 与 JSON 两种 Front Matter 写法。自定义语言与分隔符TOML 示例实战gray-matter 默认支持的语言有限但 Metalsmith 通过engines选项开放了扩展能力。仓库中的另一个测试夹具 test/fixtures/read-frontmatter-custom/src/index.md 展示了 TOML 场景~~~ thing true ~~~ An excerpt ~~~它同时改变了三件事分隔符从---变为~~~、语言从yaml变为toml、并启用了excerpt提取。对应的测试配置test/index.jsconst toml require(toml) Metalsmith(fixture(read-frontmatter-custom)) .frontmatter({ engines: { toml: toml.parse.bind(toml) }, language: toml, excerpt_separator: ~~~, delimiters: ~~~, excerpt: true }) .use((fileObj) { files fileObj }) .process(function (err) { assert.strictEqual(files[index.md].thing, true) assert.strictEqual(files[index.md].excerpt.trim(), An excerpt) done() })测试断言了两个结果thing被解析为true且excerpt属性被截取为An excerpt。这一配置组合在实际项目中非常实用——例如团队规范要求使用 TOML 写配置时可以无缝切换。excerpt摘要提取原理当excerpt: true时Matter.prototype.parse会执行摘要提取逻辑lib/matter.jsif (this[_options].excerpt parsed.excerpt) { result.excerpt parsed.excerpt.trim() // 从 contents 中剥离摘要与分隔符 parsed.content parsed.content.replace( new RegExp(^${result.excerpt}\\s*${this[_options].excerpt_separator}\\s*), ) }工作过程分两步gray-matter 依据excerpt_separator在正文中寻找分隔行将分隔行之前的内容识别为摘要Metalsmith 将摘要存入result.excerpt并从contents中移除摘要与分隔符本身确保正文纯净不会在渲染时重复输出。这正是read-frontmatter-customfixture 中An excerpt行之后又以~~~收尾的原因——它充当正文内的摘要分隔符。这一机制让“列表页显示摘要、详情页显示全文”的博客模式变得非常简单。无效 Front Matter 的容错处理如果源文件中的 Front Matter 语法有误Metalsmith 不会静默吞掉错误。从 lib/index.js 可以看到matter.parse抛出异常时会被捕获并包装为带code: invalid_frontmatter的 Errortry { ret this.matter.parse(buffer) } catch { const err new Error(Invalid frontmatter in the file at: file) err.code invalid_frontmatter return Promise.reject(err) }对应的无效夹具 test/fixtures/read-invalid-frontmatter/src/index.md 内容为--- - a b: test --- Body这是一个缩进错乱的 YAML 序列列表项后错误地缩进了键值对无法被 YAML 解析器接受。遇到此类文件时构建会以invalid_frontmatter错误终止便于你快速定位问题文件。因此在实际项目中建议在写入 Front Matter 时严格遵循 YAML 缩进规范并在 CI 中尽早暴露此类错误。与文件模式、静态文件的协同Front Matter 解析只是read阶段的一部分。对每个文件Metalsmith 还会同时维护两个与解析无关的属性mode文件的 Unix 权限位八进制字符串读取自fs.Stats写入时用于还原文件权限statsfs.Stats实例可被插件用于判断文件大小、修改时间等。此外被ignore或match规则命中的静态文件如CNAME、图片、样式表不会走 Front Matter 解析路径而是直接以contents: Buffer.from(p)内容即其路径字符串见 lib/index.js的形态进入文件集合后续由插件如 test/fixtures/static/src 场景按需处理。这一设计保证了二进制与非文本资源不会被误解析。从测试夹具到生产实践三步上手将上述机制落地到你的 Metalsmith 项目中可以按三步走第一步在源文件中声明元数据。在src目录下的 Markdown 文件开头书写 YAML Front Matter例如--- title: 我的第一篇文章 date: 2024-01-01 tags: [metalsmith, frontmatter] layout: post.hbs --- 正文内容……第二步按需配置 frontmatter()。在metalsmith.json或构建脚本中声明{ source: src, destination: build, frontmatter: { excerpt: true, excerpt_separator: --- } }metalsmith.json可识别的顶层选项包括source、destination、concurrency、metadata、clean和frontmatter见 README.md。也可以在脚本中链式调用metalsmith.frontmatter({ excerpt: true })。第三步在插件或模板中消费元数据。读取阶段完成后插件拿到的每个文件对象都已包含 Front Matter 字段。例如 draft 插件可依据draft: true过滤未发布的文章参考 examples/drafts-plugin/index.js布局模板则可通过title、date、tags等字段渲染页面。至此一条从 YAML 元数据到最终 HTML 的完整流水线便贯通了。小结Metalsmith 的 Front Matter 机制虽然入口只是一个两行---包裹的 YAML 块如test/fixtures/read-frontmatter/src/index.md所示但其背后串联起了完整的读取、解析、元数据挂载与容错体系frontmatter()API 控制开关与 gray-matter 选项Matter.parse负责分离元数据与正文excerpt机制支撑摘要场景engines扩展支持 TOML 等自定义语言而invalid_frontmatter错误码保证了错误可定位。掌握这一层机制你就能更自如地驾驭内容元数据驱动的静态站点构建。赞分享开发工具CLI前端【免费下载链接】metalsmithAn extremely simple, pluggable static site generator for Node.js项目地址https://gitcode.com/gh_mirrors/me/metalsmith点击查看免费下载相关推荐MarkText前端元数据使用YAML front matter的完整教程MarkText前端元数据使用YAML front matter的完整教程 MarkText作为一款优雅的Markdown编辑器提供了强大的YAML fro桌面应用富文本Forge Code 技能机制详解SKILL.md 的 YAML Front Matter 元数据规范与解析原理Forge Code 技能机制详解SKILL.md 的 YAML Front Matter 元数据规范与解析原理 本篇文章以 Forge Codeforge人工智能AI Agent代码智能体AI 应用CLI开发工具Markdig YAML Front Matter解析元数据管理的完整指南Markdig YAML Front Matter解析元数据管理的完整指南 YAML Front Matter是Markdown文档中用于存储元数据的强大工具开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考