eslint-plugin-unicorn 的 require-frontmatter-fields 规则为 Markdown 集合强制统一的 YAML Frontmatter 字段【免费下载链接】eslint-plugin-unicornMore than 300 powerful ESLint rules项目地址: https://gitcode.com/GitHub_Trending/es/eslint-plugin-unicornrequire-frontmatter-fields是 eslint-plugin-unicorn 中面向 Markdown 的规则之一用于在博客文章、文档页面等 Markdown 集合中强制要求顶层 YAML Frontmatter 必须包含指定字段如title、description、date从而保证元数据的一致性与完整性。本文将以 规则文档 为主体结合 规则源码、测试用例 与 快照报告讲解该规则的启用方式、配置项、行为边界与底层实现原理。规则定位为 Markdown 集合建立元数据约束在基于 Markdown 的内容体系中Frontmatter 是承载文章元数据的事实标准——博客的title、description、date文档站的layout、order以及静态站点生成器的各类自定义字段。当内容由多人协作维护时经常出现部分文章漏写关键字段导致索引、摘要、归档等功能出现缺口。require-frontmatter-fields解决的正是这一问题它读取 Markdown 文件顶部的 YAML Frontmatter检查其中是否包含你配置的全部必填字段缺失即报告错误。从 readme.md 的规则索引表可以看到该规则默认未启用在recommended与unopinionated配置中均为空也没有提供自动修复或建议修复因此需要用户按需在自定义配置中显式开启。启用前提先让 ESLint 能解析 Markdown 与 Frontmatter该规则本身不负责解析 Markdown 或识别 Frontmatter它只处理eslint/markdown已经解析出的 YAML 节点。因此启用前必须完成两步配置引入eslint/markdown插件并指定 Markdown 语言在languageOptions.frontmatter中开启yaml解析。规则文档给出的完整 flat config 示例来自 docs/rules/require-frontmatter-fields.mdimport markdown from eslint/markdown; import unicorn from eslint-plugin-unicorn; import {defineConfig} from eslint/config; export default defineConfig([ { files: [**/*.md], plugins: { markdown, unicorn, }, language: markdown/gfm, languageOptions: { frontmatter: yaml, }, rules: { unicorn/require-frontmatter-fields: [ error, { fields: [ title, description, date, ], }, ], }, }, ]);几点注意language可以使用markdown/gfm或markdown/commonmark。从 规则源码 的meta.languages声明可以看出规则声明支持markdown/commonmark与markdown/gfm两种语言此外js/js也在列表中——这是为了让configs.all将所有规则应用到 JS 文件时保持兼容此时规则只会监听不会出现的yaml节点不会产生副作用。languageOptions.frontmatter: yaml必须显式声明否则 Markdown 处理器不会提取 Frontmatter规则自然也无法检查。该规则属于 unicorn 插件必须同时注册unicorn插件才能使用unicorn/require-frontmatter-fields规则名。规则本身已在 rules/index.js 中注册导出。选项详解fields该规则只有一个选项fields用于声明必填的顶层字段名列表。属性值类型string[]默认值[]约束数组元素必须是非空字符串且不可重复uniqueItems: true从 规则源码 的 schema 定义可以看到fields是对象类型的唯一允许属性additionalProperties: false传入未知选项会直接触发配置校验错误每个元素必须是minLength: 1的字符串空字符串不可用元素不可重复未传选项时使用defaultOptions: [{fields: []}]即默认不要求任何字段。行为边界只查“顶层字段是否存在”其余一律不干预规则文档明确划定了检查范围理解这些边界对实际使用至关重要检查什么只检查顶层 YAML 映射mapping中的字段是否存在只检查存在性字段有值即通过——无论值是字符串、数字、布尔、数组还是null如date:这种空值形式只要键出现即视为满足。不检查什么不强制要求存在 Frontmatter没有 YAML Frontmatter 的 Markdown 文件会被直接忽略不会报错不校验字段的值值的类型、内容、格式一律不管不检查嵌套字段metadata.title不算满足title不检查字段顺序不检查 TOML Frontmatter 或 JSON Frontmatter只针对 YAML格式错误的 YAML 被忽略解析失败的文件直接跳过不报告。这些边界在 测试用例 中有逐一对应的验证例如完全不含 Frontmatter 的# Title通过检查valid 用例title HelloTOML 形式frontmatter: toml通过检查{title: Hello}JSON 形式frontmatter: json通过检查title: [HelloYAML 语法错误通过检查title: *missing未解析的 YAML 别名通过检查title: Hello但配置要求title、description、date三个字段时报出两个错误missingdescription、missingdate。源码实现剖析yaml 解析 顶层标量键收集规则的核心逻辑集中在 rules/require-frontmatter-fields.js 的create函数与getFieldNames辅助函数中实现相当精简空配置短路fields.length 0时create直接返回不注册任何监听器零开销监听yaml节点通过context.on(yaml, ...)监听eslint/markdown解析出的每个 YAML Frontmatter 节点该监听方式对应 ESLint 的 language plugin 机制解析 YAML调用yaml包的parseDocument(node.value)得到 YAML 文档对象双重错误防御document.errors.length 0时直接返回跳过格式错误的 YAML再通过document.toString()探测未解析的别名unresolved alias——这类错误不会进入document.errors但会在此处抛出异常捕获后同样跳过源码注释明确说明了这一细节收集顶层字段名getFieldNames先判断isMap(document.contents)——只有文档根节点是映射时才继续然后过滤出键为标量isScalar(pair.key)且值为字符串typeof pair.key.value string的键收集进Set。这意味着非映射根节点如 YAML 序列- title: Hello和复杂键如? [complex, key]都不会被计入相关边界同样在测试中有对应用例逐一比对并报告遍历配置的fields凡不在fieldNames集合中的字段均产出missing-field错误消息模板为Missing required frontmatter field {{field}}.源码报告位置指向整个 YAML 节点。从元信息看该规则的类型为suggestion源码docs.recommended为false与规则文档中“在recommended、unopinionated配置中默认禁用”的描述一致。真实报错形态快照报告中的实际输出测试快照 记录了规则在 AVA 测试环境下的真实输出可以帮助你预期集成到 CI 后的报错形态。以“只有title但要求三个字段”的文件为例--- title: Hello --- # Hello配置fields: [title, description, date]时会产生两条错误 1 | --- | ^^^ 2 | title: Hello | ^^^^^^^^^^^^ 3 | --- | ^^^ Missing required frontmatter field description. ... Missing required frontmatter field date.类似的报错模式还覆盖了空 Frontmatter---\n---缺失title、序列形式的 Frontmatter- title: Hello三个字段全部缺失、嵌套字段metadata: {title: Hello}缺失顶层title以及复杂键混合场景。实战建议何时启用适合博客站、文档站、内容型仓库等所有“每篇文章必须携带一致元数据”的场景与静态站点生成器SSG的内容管线配合效果最佳——先由 ESLint 在 CI 阶段拦截缺失字段再交给构建系统消费 Frontmatter。字段清单保持克制只把真正被消费的字段列入fields避免要求与内容无关的键导致协作摩擦空值如date:也算“存在”如需校验值格式可配合其他校验手段。不要依赖它校验 TOML/JSON Frontmatter该规则明确只针对 YAML其他格式请使用对应生态工具。结合eslint/markdown的配置务必同时设置language与languageOptions.frontmatter: yaml否则规则形同虚设缺少任一环节时规则不报错也不工作容易造成“规则没生效”的错觉。运行验证仓库使用 AVA 运行测试相关用例集中在 test/require-frontmatter-fields.js可通过npm run test:jsava执行快照文件 test/snapshots/require-frontmatter-fields.js.md 用于回归校验报错输出。总而言之require-frontmatter-fields是 eslint-plugin-unicorn 中面向内容工程的一把“小且准”的尺子它只做顶层 YAML 字段存在性检查边界清晰、实现透明配合eslint/markdown即可低成本地为整个 Markdown 集合建立统一的元数据规范。【免费下载链接】eslint-plugin-unicornMore than 300 powerful ESLint rules项目地址: https://gitcode.com/GitHub_Trending/es/eslint-plugin-unicorn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
eslint-plugin-unicorn 的 require-frontmatter-fields 规则：为 Markdown 集合强制统一的 YAML Frontmatter 字段
eslint-plugin-unicorn 的 require-frontmatter-fields 规则为 Markdown 集合强制统一的 YAML Frontmatter 字段【免费下载链接】eslint-plugin-unicornMore than 300 powerful ESLint rules项目地址: https://gitcode.com/GitHub_Trending/es/eslint-plugin-unicornrequire-frontmatter-fields是 eslint-plugin-unicorn 中面向 Markdown 的规则之一用于在博客文章、文档页面等 Markdown 集合中强制要求顶层 YAML Frontmatter 必须包含指定字段如title、description、date从而保证元数据的一致性与完整性。本文将以 规则文档 为主体结合 规则源码、测试用例 与 快照报告讲解该规则的启用方式、配置项、行为边界与底层实现原理。规则定位为 Markdown 集合建立元数据约束在基于 Markdown 的内容体系中Frontmatter 是承载文章元数据的事实标准——博客的title、description、date文档站的layout、order以及静态站点生成器的各类自定义字段。当内容由多人协作维护时经常出现部分文章漏写关键字段导致索引、摘要、归档等功能出现缺口。require-frontmatter-fields解决的正是这一问题它读取 Markdown 文件顶部的 YAML Frontmatter检查其中是否包含你配置的全部必填字段缺失即报告错误。从 readme.md 的规则索引表可以看到该规则默认未启用在recommended与unopinionated配置中均为空也没有提供自动修复或建议修复因此需要用户按需在自定义配置中显式开启。启用前提先让 ESLint 能解析 Markdown 与 Frontmatter该规则本身不负责解析 Markdown 或识别 Frontmatter它只处理eslint/markdown已经解析出的 YAML 节点。因此启用前必须完成两步配置引入eslint/markdown插件并指定 Markdown 语言在languageOptions.frontmatter中开启yaml解析。规则文档给出的完整 flat config 示例来自 docs/rules/require-frontmatter-fields.mdimport markdown from eslint/markdown; import unicorn from eslint-plugin-unicorn; import {defineConfig} from eslint/config; export default defineConfig([ { files: [**/*.md], plugins: { markdown, unicorn, }, language: markdown/gfm, languageOptions: { frontmatter: yaml, }, rules: { unicorn/require-frontmatter-fields: [ error, { fields: [ title, description, date, ], }, ], }, }, ]);几点注意language可以使用markdown/gfm或markdown/commonmark。从 规则源码 的meta.languages声明可以看出规则声明支持markdown/commonmark与markdown/gfm两种语言此外js/js也在列表中——这是为了让configs.all将所有规则应用到 JS 文件时保持兼容此时规则只会监听不会出现的yaml节点不会产生副作用。languageOptions.frontmatter: yaml必须显式声明否则 Markdown 处理器不会提取 Frontmatter规则自然也无法检查。该规则属于 unicorn 插件必须同时注册unicorn插件才能使用unicorn/require-frontmatter-fields规则名。规则本身已在 rules/index.js 中注册导出。选项详解fields该规则只有一个选项fields用于声明必填的顶层字段名列表。属性值类型string[]默认值[]约束数组元素必须是非空字符串且不可重复uniqueItems: true从 规则源码 的 schema 定义可以看到fields是对象类型的唯一允许属性additionalProperties: false传入未知选项会直接触发配置校验错误每个元素必须是minLength: 1的字符串空字符串不可用元素不可重复未传选项时使用defaultOptions: [{fields: []}]即默认不要求任何字段。行为边界只查“顶层字段是否存在”其余一律不干预规则文档明确划定了检查范围理解这些边界对实际使用至关重要检查什么只检查顶层 YAML 映射mapping中的字段是否存在只检查存在性字段有值即通过——无论值是字符串、数字、布尔、数组还是null如date:这种空值形式只要键出现即视为满足。不检查什么不强制要求存在 Frontmatter没有 YAML Frontmatter 的 Markdown 文件会被直接忽略不会报错不校验字段的值值的类型、内容、格式一律不管不检查嵌套字段metadata.title不算满足title不检查字段顺序不检查 TOML Frontmatter 或 JSON Frontmatter只针对 YAML格式错误的 YAML 被忽略解析失败的文件直接跳过不报告。这些边界在 测试用例 中有逐一对应的验证例如完全不含 Frontmatter 的# Title通过检查valid 用例title HelloTOML 形式frontmatter: toml通过检查{title: Hello}JSON 形式frontmatter: json通过检查title: [HelloYAML 语法错误通过检查title: *missing未解析的 YAML 别名通过检查title: Hello但配置要求title、description、date三个字段时报出两个错误missingdescription、missingdate。源码实现剖析yaml 解析 顶层标量键收集规则的核心逻辑集中在 rules/require-frontmatter-fields.js 的create函数与getFieldNames辅助函数中实现相当精简空配置短路fields.length 0时create直接返回不注册任何监听器零开销监听yaml节点通过context.on(yaml, ...)监听eslint/markdown解析出的每个 YAML Frontmatter 节点该监听方式对应 ESLint 的 language plugin 机制解析 YAML调用yaml包的parseDocument(node.value)得到 YAML 文档对象双重错误防御document.errors.length 0时直接返回跳过格式错误的 YAML再通过document.toString()探测未解析的别名unresolved alias——这类错误不会进入document.errors但会在此处抛出异常捕获后同样跳过源码注释明确说明了这一细节收集顶层字段名getFieldNames先判断isMap(document.contents)——只有文档根节点是映射时才继续然后过滤出键为标量isScalar(pair.key)且值为字符串typeof pair.key.value string的键收集进Set。这意味着非映射根节点如 YAML 序列- title: Hello和复杂键如? [complex, key]都不会被计入相关边界同样在测试中有对应用例逐一比对并报告遍历配置的fields凡不在fieldNames集合中的字段均产出missing-field错误消息模板为Missing required frontmatter field {{field}}.源码报告位置指向整个 YAML 节点。从元信息看该规则的类型为suggestion源码docs.recommended为false与规则文档中“在recommended、unopinionated配置中默认禁用”的描述一致。真实报错形态快照报告中的实际输出测试快照 记录了规则在 AVA 测试环境下的真实输出可以帮助你预期集成到 CI 后的报错形态。以“只有title但要求三个字段”的文件为例--- title: Hello --- # Hello配置fields: [title, description, date]时会产生两条错误 1 | --- | ^^^ 2 | title: Hello | ^^^^^^^^^^^^ 3 | --- | ^^^ Missing required frontmatter field description. ... Missing required frontmatter field date.类似的报错模式还覆盖了空 Frontmatter---\n---缺失title、序列形式的 Frontmatter- title: Hello三个字段全部缺失、嵌套字段metadata: {title: Hello}缺失顶层title以及复杂键混合场景。实战建议何时启用适合博客站、文档站、内容型仓库等所有“每篇文章必须携带一致元数据”的场景与静态站点生成器SSG的内容管线配合效果最佳——先由 ESLint 在 CI 阶段拦截缺失字段再交给构建系统消费 Frontmatter。字段清单保持克制只把真正被消费的字段列入fields避免要求与内容无关的键导致协作摩擦空值如date:也算“存在”如需校验值格式可配合其他校验手段。不要依赖它校验 TOML/JSON Frontmatter该规则明确只针对 YAML其他格式请使用对应生态工具。结合eslint/markdown的配置务必同时设置language与languageOptions.frontmatter: yaml否则规则形同虚设缺少任一环节时规则不报错也不工作容易造成“规则没生效”的错觉。运行验证仓库使用 AVA 运行测试相关用例集中在 test/require-frontmatter-fields.js可通过npm run test:jsava执行快照文件 test/snapshots/require-frontmatter-fields.js.md 用于回归校验报错输出。总而言之require-frontmatter-fields是 eslint-plugin-unicorn 中面向内容工程的一把“小且准”的尺子它只做顶层 YAML 字段存在性检查边界清晰、实现透明配合eslint/markdown即可低成本地为整个 Markdown 集合建立统一的元数据规范。【免费下载链接】eslint-plugin-unicornMore than 300 powerful ESLint rules项目地址: https://gitcode.com/GitHub_Trending/es/eslint-plugin-unicorn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考