企业官网建设流程全解析

面向 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）中强制执行的内容规则，这是整份规范的核心：

1. 标题（Headings）：使用合适的标题层级（H2、H3 等）组织内容；不得使用 H1，因为 H1 会依据文章标题自动生成。这一点在博客体系中有直接体现——website/blog 下的文章通常以---front matter 携带title元数据，正文从 H2 起步。
2. 列表（Lists）：列表须使用项目符号或数字编号，并保证正确的缩进与间距。
3. 代码块（Code Blocks）：使用围栏代码块（fenced code blocks），并指定语言以便语法高亮。
4. 链接（Links）：使用规范的 Markdown 链接语法，保证链接有效、可访问。
5. 图片（Images）：使用规范的图片语法，必须包含 alt 文本以保证无障碍访问。
6. 表格（Tables）：表格数据使用 Markdown 表格，保证格式正确、列对齐。
7. 行长度（Line Length）：将单行长度限制在120 字符以内以保证可读性。
8. 空白（Whitespace）：用适当的空白分隔章节、提升可读性，同时避免过度空白。
9. 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 text，alt 文本需简要描述图片内容。

• 表格：用|构建表格，保证列对齐并包含表头。

• 行长度：在 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 与仓库配置，提交文档前可对照以下清单逐项检查：

简言之：规范定基线，配置调豁免，命令做验证——这就是 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