awesome-copilot Markdown 内容创作规范面向博客文章的编写、校验与质量基线【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文以 awesome-copilot 仓库中的 markdown-content-creation.instructions.md 为主线系统讲解在 GitHub Copilot 生态下编写高质量 Markdown 博客内容时必须遵守的内容规则、格式结构指南与可执行校验清单并结合仓库中 CommonMark 规范文档、GFM 规范文档 与 eng/lib/markdown.test.mjs 等源码佐证帮助读者掌握一套可复现、可校验、可被搜索引擎与 LLM 稳定解析的文档生产基线。一、文档定位一份面向博客发布的 Markdown 内容规则instructions/markdown-content-creation.instructions.md是 awesome-copilot 仓库中专门针对「博客文章blog posts」的 Markdown 内容创作标准。它通过 YAML front matter 声明自身的作用范围与适用目标--- description: Markdown guidelines and content creation standards for blog posts applyTo: **/*.md ---description说明该指令文件的用途——为博客文章提供 Markdown 指南与内容创作标准。applyTo: **/*.md声明该规则将应用于仓库中所有 Markdown 文件这与仓库中其他指令文件如 markdown.instructions.md、markdown-gfm.instructions.md使用相同的applyTo声明模式保持一致便于 Copilot 在编辑.md文件时自动加载对应规则。从仓库整体结构看这份指令与 docs/README.instructions.md 所描述的「Custom Instructions」机制配合使用将*.instructions.md文件放入工作区的.github/instructions/目录或合并进.github/copilot-instructions.md后规则会自动作用于 Copilot 的补全与审查行为。二、核心内容规则写 Markdown 前必须遵守的 9 条基线文档明确说明以下规则在「校验器validators」中被强制执行而非仅作建议。任何面向博客发布的 Markdown 内容都应逐条对照#规则要点说明1标题Headings使用恰当的标题层级H2、H3 等组织内容不要使用 H1H1 将根据文章标题title自动生成2列表Lists使用项目符号或编号列表保证正确的缩进与间距3代码块Code Blocks使用围栏式代码块并指定语言以启用语法高亮4链接Links使用标准的 Markdown 链接语法确保链接有效且可访问5图片Images使用标准图片语法必须包含 alt 文本以保证可访问性6表格Tables使用 Markdown 表格呈现数据保证格式与对齐正确7行长度Line Length单行长度限制在 400 字符以内保证可读性8空白Whitespace使用恰当的空白分隔各章节提升可读性避免过量空白9Front Matter文件开头必须包含 YAML front matter携带必需的元数据字段2.1 为什么「禁止使用 H1」如此关键规则 1 是该文档最容易被忽略但影响最深的一条正文中禁止出现 H1。原因在于发布管线会基于文章的post_title元数据自动生成 H1 标题详见下文「Front Matter 校验清单」。如果正文中再手写一个 H1会导致页面出现重复的一级标题破坏文档大纲结构与 SEO 语义。2.2 行长度与可读性的工程化落地规则 7 给出 400 字符的硬上限而在「Formatting and Structure」一节中进一步建议日常编辑时按80 字符断行、长段落使用软换行。仓库中的 eng/lib/markdown.test.mjs 从工具层印证了这类文本处理边界的工程化思路——例如其inlineCode工具会将值截断到 80 字符并对超过最长反引号串的内容自动选择更长的围栏确保生成的代码片段既符合 Markdown 语法又不会撑破行宽约束。这说明「行长度」不只是审美偏好而是会被写成可执行断言与格式化工具的质量约束。三、格式与结构指南具体语法怎么写文档给出了逐条细化的语法要求是 9 条规则的可执行版本标题使用##表示 H2、###表示 H3标题必须按层级使用。如果内容中出现 H4建议重构出现 H5则强烈建议重构——即文档结构不应嵌套过深。列表项目符号统一用-编号列表用1.嵌套列表使用两个空格缩进。代码块使用三重反引号创建围栏式代码块开头的反引号后必须指定语言以便语法高亮例如csharp。这与 markdown.instructions.md 中「围栏代码块必须以 3 反引号或波浪线开头且不得混用、闭合围栏字符数不得少于开启围栏」的 CommonMark 细则一致。链接使用link text语法链接文本要有描述性URL 必须有效。CommonMark 细则还要求链接文本与(或[之间不能有空白参见 markdown.instructions.md 的 Inlines 章节。图片使用alt text语法alt 文本中简要描述图片内容。图片 alt 文本不能为空CommonMark 校验清单同样要求非空 alt。表格使用|创建表格列需对齐且必须包含表头。GFM 规范markdown-gfm.instructions.md进一步要求表头行 分隔行---、:---:、---: 数据行列数必须匹配字面管道符需用\|转义。行长度按 80 字符断行长段落使用软换行即普通换行浏览器会渲染为空格。空白使用空行分隔章节避免过量空白。注意「紧凑列表」与「松散列表」由列表项之间是否存在空行决定CommonMark 细则。四、验证清单让内容可被机器检查文档的核心价值在于其「Validation Checklist」——它把抽象的写作规范转译成了逐项可勾选的验收标准分为 Front Matter 与内容格式两大类。4.1 Front Matter 元数据清单9 个字段博客文章必须携带以下 YAML front matter 字段这是发布系统解析文章元数据的基础字段说明备注post_title文章标题最终 H1 的来源author1主要作者文章的主作者post_slugURL 中的文章 slug决定文章地址microsoft_alias作者的 Microsoft 别名组织内身份标识featured_image头图 URL文章的精选配图categories文章分类必须取自/categories.txt中定义的分类列表tags文章标签用于检索与聚合ai_note是否使用 AI 参与创作记录 AI 使用情况summary文章摘要尽可能基于内容自动推荐摘要post_date发布日期文章的发布时间一个符合规范的 front matter 示例--- post_title: Using Custom Instructions to Enforce Markdown Quality author1: Jane Doe post_slug: enforce-markdown-quality-with-copilot microsoft_alias: janedoe featured_image: https://example.com/images/cover.png categories: [Documentation] tags: [markdown, copilot, content-creation] ai_note: true summary: How to leverage GitHub Copilot custom instructions to enforce consistent Markdown content quality. post_date: 2026-01-15 ---值得注意的约束是categories字段其取值必须来自/categories.txt中预定义的分类列表这保证了发布站的分类体系是受控的、可聚合的而不是作者随意发明的标签。该约束体现了「受控词汇表」这一内容治理实践。4.2 内容与格式清单内容遵循上述 Markdown 内容规则。内容按指南正确格式化与结构化。已运行校验工具检查规则与指南的符合性。这份清单同时强调了一个工作流要点写完后要实际运行校验工具而不是仅靠肉眼审查。这与仓库中 CommonMark 指令markdown.instructions.md内置的校验清单互为补充——后者把标题、围栏代码块、链接、autolink、HTML 块等底层语法规则也纳入了机器可查的范围。五、仓库内的延伸依据规则背后的规范与工具awesome-copilot 为这份内容规则提供了配套的规范文档与工程工具可作为深入研读的入口markdown.instructions.md按 CommonMark 规范 0.31.2 细化 Markdown 语法规则包括 ATX 标题、围栏代码块、块引用、列表项缩进规则、行内强调_不能用于单词内部、autolink 必须使用尖括号等底层细则。markdown-gfm.instructions.mdGFM 是 CommonMark 的严格超集额外覆盖表格、任务列表、删除线、裸 URL 自动链接、禁用原始 HTML 标签如script、style等扩展规则并附有对应的校验清单。eng/lib/markdown.test.mjs以单元测试形式验证 Markdown 文本工具如inlineCode的反引号围栏选择、空白折叠与 80 字符截断行为展示了「规范 → 工具 → 测试」的完整工程化链条。三份材料的关系可以概括为内容创作规则本文档定义「写什么、结构如何」CommonMark/GFM 指令定义「语法如何解析」而 eng 下的工具与测试确保「文本处理结果可预期」。六、工作流建议从规则到可发布内容结合 docs/README.instructions.md 中关于自定义指令的用法说明推荐如下落地工作流安装指令将 markdown-content-creation.instructions.md 复制到工作区.github/instructions/目录或合并进.github/copilot-instructions.md让 Copilot 在编写.md文件时自动应用规则。起草正文一律从 H2 开始组织层级H1 留给发布系统代码块标注语言图片带非空 alt 文本表格保证表头与列对齐。填充元数据在文件头部写全 10 个 front matter 字段categories严格从/categories.txt中取值。机器校验运行仓库中或项目内配置的校验工具对照本文第四节的 Checklist 逐项确认重点检查 H1 缺失、链接可达性、行长度上限与图片 alt 完整性。发布由管线依据post_title生成 H1依据post_slug生成 URL依据categories/tags完成内容聚合。按照这套流程产出的文章既满足机器可校验的结构化要求也天然具备清晰的大纲层级与可读性从而更容易被搜索引擎、Agent 与 LLM 稳定地检索和引用。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 awesome-copilot Markdown 内容创作规范：面向博客文章的编写、校验与质量基线
awesome-copilot Markdown 内容创作规范面向博客文章的编写、校验与质量基线【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文以 awesome-copilot 仓库中的 markdown-content-creation.instructions.md 为主线系统讲解在 GitHub Copilot 生态下编写高质量 Markdown 博客内容时必须遵守的内容规则、格式结构指南与可执行校验清单并结合仓库中 CommonMark 规范文档、GFM 规范文档 与 eng/lib/markdown.test.mjs 等源码佐证帮助读者掌握一套可复现、可校验、可被搜索引擎与 LLM 稳定解析的文档生产基线。一、文档定位一份面向博客发布的 Markdown 内容规则instructions/markdown-content-creation.instructions.md是 awesome-copilot 仓库中专门针对「博客文章blog posts」的 Markdown 内容创作标准。它通过 YAML front matter 声明自身的作用范围与适用目标--- description: Markdown guidelines and content creation standards for blog posts applyTo: **/*.md ---description说明该指令文件的用途——为博客文章提供 Markdown 指南与内容创作标准。applyTo: **/*.md声明该规则将应用于仓库中所有 Markdown 文件这与仓库中其他指令文件如 markdown.instructions.md、markdown-gfm.instructions.md使用相同的applyTo声明模式保持一致便于 Copilot 在编辑.md文件时自动加载对应规则。从仓库整体结构看这份指令与 docs/README.instructions.md 所描述的「Custom Instructions」机制配合使用将*.instructions.md文件放入工作区的.github/instructions/目录或合并进.github/copilot-instructions.md后规则会自动作用于 Copilot 的补全与审查行为。二、核心内容规则写 Markdown 前必须遵守的 9 条基线文档明确说明以下规则在「校验器validators」中被强制执行而非仅作建议。任何面向博客发布的 Markdown 内容都应逐条对照#规则要点说明1标题Headings使用恰当的标题层级H2、H3 等组织内容不要使用 H1H1 将根据文章标题title自动生成2列表Lists使用项目符号或编号列表保证正确的缩进与间距3代码块Code Blocks使用围栏式代码块并指定语言以启用语法高亮4链接Links使用标准的 Markdown 链接语法确保链接有效且可访问5图片Images使用标准图片语法必须包含 alt 文本以保证可访问性6表格Tables使用 Markdown 表格呈现数据保证格式与对齐正确7行长度Line Length单行长度限制在 400 字符以内保证可读性8空白Whitespace使用恰当的空白分隔各章节提升可读性避免过量空白9Front Matter文件开头必须包含 YAML front matter携带必需的元数据字段2.1 为什么「禁止使用 H1」如此关键规则 1 是该文档最容易被忽略但影响最深的一条正文中禁止出现 H1。原因在于发布管线会基于文章的post_title元数据自动生成 H1 标题详见下文「Front Matter 校验清单」。如果正文中再手写一个 H1会导致页面出现重复的一级标题破坏文档大纲结构与 SEO 语义。2.2 行长度与可读性的工程化落地规则 7 给出 400 字符的硬上限而在「Formatting and Structure」一节中进一步建议日常编辑时按80 字符断行、长段落使用软换行。仓库中的 eng/lib/markdown.test.mjs 从工具层印证了这类文本处理边界的工程化思路——例如其inlineCode工具会将值截断到 80 字符并对超过最长反引号串的内容自动选择更长的围栏确保生成的代码片段既符合 Markdown 语法又不会撑破行宽约束。这说明「行长度」不只是审美偏好而是会被写成可执行断言与格式化工具的质量约束。三、格式与结构指南具体语法怎么写文档给出了逐条细化的语法要求是 9 条规则的可执行版本标题使用##表示 H2、###表示 H3标题必须按层级使用。如果内容中出现 H4建议重构出现 H5则强烈建议重构——即文档结构不应嵌套过深。列表项目符号统一用-编号列表用1.嵌套列表使用两个空格缩进。代码块使用三重反引号创建围栏式代码块开头的反引号后必须指定语言以便语法高亮例如csharp。这与 markdown.instructions.md 中「围栏代码块必须以 3 反引号或波浪线开头且不得混用、闭合围栏字符数不得少于开启围栏」的 CommonMark 细则一致。链接使用link text语法链接文本要有描述性URL 必须有效。CommonMark 细则还要求链接文本与(或[之间不能有空白参见 markdown.instructions.md 的 Inlines 章节。图片使用alt text语法alt 文本中简要描述图片内容。图片 alt 文本不能为空CommonMark 校验清单同样要求非空 alt。表格使用|创建表格列需对齐且必须包含表头。GFM 规范markdown-gfm.instructions.md进一步要求表头行 分隔行---、:---:、---: 数据行列数必须匹配字面管道符需用\|转义。行长度按 80 字符断行长段落使用软换行即普通换行浏览器会渲染为空格。空白使用空行分隔章节避免过量空白。注意「紧凑列表」与「松散列表」由列表项之间是否存在空行决定CommonMark 细则。四、验证清单让内容可被机器检查文档的核心价值在于其「Validation Checklist」——它把抽象的写作规范转译成了逐项可勾选的验收标准分为 Front Matter 与内容格式两大类。4.1 Front Matter 元数据清单9 个字段博客文章必须携带以下 YAML front matter 字段这是发布系统解析文章元数据的基础字段说明备注post_title文章标题最终 H1 的来源author1主要作者文章的主作者post_slugURL 中的文章 slug决定文章地址microsoft_alias作者的 Microsoft 别名组织内身份标识featured_image头图 URL文章的精选配图categories文章分类必须取自/categories.txt中定义的分类列表tags文章标签用于检索与聚合ai_note是否使用 AI 参与创作记录 AI 使用情况summary文章摘要尽可能基于内容自动推荐摘要post_date发布日期文章的发布时间一个符合规范的 front matter 示例--- post_title: Using Custom Instructions to Enforce Markdown Quality author1: Jane Doe post_slug: enforce-markdown-quality-with-copilot microsoft_alias: janedoe featured_image: https://example.com/images/cover.png categories: [Documentation] tags: [markdown, copilot, content-creation] ai_note: true summary: How to leverage GitHub Copilot custom instructions to enforce consistent Markdown content quality. post_date: 2026-01-15 ---值得注意的约束是categories字段其取值必须来自/categories.txt中预定义的分类列表这保证了发布站的分类体系是受控的、可聚合的而不是作者随意发明的标签。该约束体现了「受控词汇表」这一内容治理实践。4.2 内容与格式清单内容遵循上述 Markdown 内容规则。内容按指南正确格式化与结构化。已运行校验工具检查规则与指南的符合性。这份清单同时强调了一个工作流要点写完后要实际运行校验工具而不是仅靠肉眼审查。这与仓库中 CommonMark 指令markdown.instructions.md内置的校验清单互为补充——后者把标题、围栏代码块、链接、autolink、HTML 块等底层语法规则也纳入了机器可查的范围。五、仓库内的延伸依据规则背后的规范与工具awesome-copilot 为这份内容规则提供了配套的规范文档与工程工具可作为深入研读的入口markdown.instructions.md按 CommonMark 规范 0.31.2 细化 Markdown 语法规则包括 ATX 标题、围栏代码块、块引用、列表项缩进规则、行内强调_不能用于单词内部、autolink 必须使用尖括号等底层细则。markdown-gfm.instructions.mdGFM 是 CommonMark 的严格超集额外覆盖表格、任务列表、删除线、裸 URL 自动链接、禁用原始 HTML 标签如script、style等扩展规则并附有对应的校验清单。eng/lib/markdown.test.mjs以单元测试形式验证 Markdown 文本工具如inlineCode的反引号围栏选择、空白折叠与 80 字符截断行为展示了「规范 → 工具 → 测试」的完整工程化链条。三份材料的关系可以概括为内容创作规则本文档定义「写什么、结构如何」CommonMark/GFM 指令定义「语法如何解析」而 eng 下的工具与测试确保「文本处理结果可预期」。六、工作流建议从规则到可发布内容结合 docs/README.instructions.md 中关于自定义指令的用法说明推荐如下落地工作流安装指令将 markdown-content-creation.instructions.md 复制到工作区.github/instructions/目录或合并进.github/copilot-instructions.md让 Copilot 在编写.md文件时自动应用规则。起草正文一律从 H2 开始组织层级H1 留给发布系统代码块标注语言图片带非空 alt 文本表格保证表头与列对齐。填充元数据在文件头部写全 10 个 front matter 字段categories严格从/categories.txt中取值。机器校验运行仓库中或项目内配置的校验工具对照本文第四节的 Checklist 逐项确认重点检查 H1 缺失、链接可达性、行长度上限与图片 alt 完整性。发布由管线依据post_title生成 H1依据post_slug生成 URL依据categories/tags完成内容聚合。按照这套流程产出的文章既满足机器可校验的结构化要求也天然具备清晰的大纲层级与可读性从而更容易被搜索引擎、Agent 与 LLM 稳定地检索和引用。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考