面向 oh-my-posh 文档仓库的 Markdown 内容规范与 markdownlint-cli2 校验工作流

面向 oh-my-posh 文档仓库的 Markdown 内容规范与 markdownlint-cli2 校验工作流【免费下载链接】oh-my-poshThe most customisable and low-latency cross platform/shell prompt renderer项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-posh本篇指南以 oh-my-posh 仓库中的 .agents/skills/markdown/SKILL.md 为骨架系统梳理该项目对.md/.mdx文件的内容规则、格式结构与编辑后验证流程。读者学完后将能在贡献文档、编写博客website/blog、撰写配置说明website/docs或创建主题文档时写出既符合规范、又能被 markdownlint 一次性通过的 Markdown并掌握如何用.markdownlint-cli2.yaml与内联指令治理长表格、代码块等真实场景。规范文档的角色Agent Skill 与项目文档的公共约定在 oh-my-posh 仓库中.agents/skills/markdown/SKILL.md是一个面向 Agent 的技能卡片其 YAML front matter 声明了技能名称markdown与适用场景——writing or editing any .md or .mdx file, including documentation and website content。也就是说它不只是给人类贡献者看的写作规范更是 AI 协作Agent、LLM 生成文档时的强制约束来源与仓库内其他技能卡片如 .agents/skills/golang/SKILL.md、.agents/skills/writing-clearly-and-concisely/SKILL.md共同构成项目的贡献者协议层。该文档将规范拆成三大块内容规则Content Rules、格式与结构Formatting and Structure、编辑后验证Post-Edit Verification最后落到验证要求Validation Requirements。下面逐层展开。九条内容规则从标题层级到 Front Matter 的完整约束SKILL.md 明确列出 9 条在校验器validators中强制执行的内容规则这是整份规范的核心标题Headings使用合适的标题层级H2、H3 等组织内容不得使用 H1因为 H1 会依据文章标题自动生成。这一点在博客体系中有直接体现——website/blog 下的文章通常以---front matter 携带title元数据正文从 H2 起步。列表Lists列表须使用项目符号或数字编号并保证正确的缩进与间距。代码块Code Blocks使用围栏代码块fenced code blocks并指定语言以便语法高亮。链接Links使用规范的 Markdown 链接语法保证链接有效、可访问。图片Images使用规范的图片语法必须包含 alt 文本以保证无障碍访问。表格Tables表格数据使用 Markdown 表格保证格式正确、列对齐。行长度Line Length将单行长度限制在120 字符以内以保证可读性。空白Whitespace用适当的空白分隔章节、提升可读性同时避免过度空白。Front Matter在文件开头包含YAML front matter携带必需的元数据字段如name、description。其中第 1 条禁用 H1与第 9 条front matter是文档类仓库常见的标题由站点框架生成模式例如 oh-my-posh 官网基于 Docusaurus 构建见 website/docusaurus.config.js页面标题由 front matter 驱动正文若再写 H1 会造成重复与层级混乱。格式与结构细则可执行的写作模板规范进一步给出每个规则的具体写法可直接照搬标题##表示 H2###表示 H3须按层级递进使用若内容出现 H4 建议重构出现 H5 则强烈建议重构。列表项目符号用-有序列表用1.嵌套列表缩进两个空格。代码块围栏代码块必须带语言标识例如fmt.Println(hello)链接支持两种形式——行内式[Docs](https://example.com/docs)与引用式[Docs][docs]引用式需在页面末尾追加定义[docs]: https://example.com/docs。图片使用alt textalt 文本需简要描述图片内容。表格用|构建表格保证列对齐并包含表头。行长度在 120 字符处断行长段落使用软换行soft line breaks。空白用空行分隔章节避免过度空白。这套细则在仓库中能找到大量落地实例例如 website/docs/configuration/data.mdx 中的导出参数表格Flag/Description两列即符合表格规范website/docs/segments/system/path.mdx 则在展示多行路径示例时使用了!-- markdownlint-disable MD033 MD049 --等内联指令。编辑后验证用 markdownlint-cli2 关闭反馈回路规范特别强调Post-Edit Verification编辑后验证每编辑完任意.md或.mdx文件后立即运行npx markdownlint-cli2 edited-file并解决所有报告的错误后再视为任务完成。这样做的目的是关闭反馈回路closes the feedback loop让违规在本地编辑阶段就被发现并修复而不是依赖外部 CI 在提交后才报告。这条命令依赖仓库根目录的 .markdownlint-cli2.yaml 配置文件详见下一节也可一次性校验整个文档目录。仓库级落地.markdownlint-cli2.yaml 的规则调优与内联指令实践规范描述的规则是默认基线而 oh-my-posh 仓库通过 .markdownlint-cli2.yaml 做了针对性调优是理解规范如何在实际仓库生效的关键证据config: MD013: line_length: 120 code_blocks: false MD024: false gitignore: true ignores: - node_modules/ - .github/agents/*.agent.md - .github/PULL_REQUEST_TEMPLATE.md - .agents/skills/ast-grep逐项解读MD013行长line_length: 120与 SKILL.md 第 7 条规则一致code_blocks: false表示代码块内部不受 120 字符限制——这解释了为什么长命令行、长路径示例可以安全地写在代码块里而不触发告警。MD024相邻标题重复全局关闭允许不同小节出现相同层级的重复标题如多个Usage小节。gitignore: true自动跳过.gitignore中列出的文件避免误扫构建产物。ignores显式排除node_modules/、GitHub Agent 定义文件、PR 模板以及.agents/skills/ast-grep目录该目录内容为 ast-grep 规则参考不参与 Markdown 校验。在正文中仓库还大量使用 markdownlint 内联注释指令来豁免不可避免的违规这是规范第 7 条120 字符的弹性补充README.md 开头使用!-- markdownlint-disable --/!-- markdownlint-enable --包围徽章 HTML 区并用!-- markdownlint-disable first-header-h1 --豁免仓库根 README 的 H1 惯例website/docs/configuration/data.mdx 第 215–229 行用!-- markdownlint-disable MD013 --/!-- markdownlint-enable MD013 --包住命令参数表格因为Flag / Description两列很难压缩进 120 字符website/docs/contributors.md 用!-- markdownlint-disable --与!-- markdownlint-restore --包围大段贡献者列表website/docs/installation/_homebrew.md 用!-- markdownlint-disable-next-line MD041 --豁免单行MD041 要求文件首行为 H1而站点文档首行应为 front matter。这些内联指令与 SKILL.md 中在编辑后立即运行npx markdownlint-cli2验证的要求形成闭环默认规则管住绝大多数文件少量结构化例外表格、徽章、站点 H1 规则则用显式指令声明豁免且声明紧贴被豁免内容、有明确作用范围不破坏整体可校验性。与相邻规范的配合Markdown 技能与写作技能的分工值得指出的是.agents/skills/markdown/SKILL.md解决的是格式与机器可校验性lint 规则、结构、语法而仓库中的 .agents/skills/writing-clearly-and-concisely/SKILL.md 解决的是文字质量主动语态、正面陈述、具体语言、删减冗余。在 website/blog 的博客文章与website/docs的配置文档中两类规范叠加使用先按 Markdown 规范保证结构与 lint 通过再按写作规范打磨措辞。对文档贡献者而言建议的完整工作流是起草 → 按本规范组织结构与格式 → 按写作规范润色 → 运行npx markdownlint-cli2 edited-file清零告警 → 提交。快速自查清单依据 SKILL.md 与仓库配置提交文档前可对照以下清单逐项检查检查项依据自检方式无 H1正文从 H2 起步SKILL.md 规则 1目视检查标题层级代码块带语言标识SKILL.md 规则 3检查围栏代码块首行所有图片含 alt 文本SKILL.md 规则 5检查...语法行长度 ≤ 120 字符代码块除外SKILL.md 规则 7 与.markdownlint-cli2.yaml的MD013运行 markdownlint文件以 YAML front matter 开头SKILL.md 规则 9目视检查文件头markdownlint 零告警SKILL.md Post-Edit Verification运行npx markdownlint-cli2 file结构性例外已用内联指令显式声明仓库内markdownlint-disable实践检索markdownlint-disable注释简言之规范定基线配置调豁免命令做验证——这就是 oh-my-posh 文档仓库把AI 生成内容与人类撰写内容统一收进同一条质量管线的完整机制也是贡献者在写任何.md/.mdx文件前应当内化的第一原则。【免费下载链接】oh-my-poshThe most customisable and low-latency cross platform/shell prompt renderer项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-posh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考