markdown-style

markdown-style

Markdown 编写与审查技能。负责两层规则以及应用这些规则的流程：

1. 语法规范——有效的 Markdown 应是什么样。基于 Markdown Guide 基础语法参考。完整规范：references/syntax-canon.md。
2. 风格叠加规则——审查者在有效语法之上强制执行的主观规则。基于 Google Markdown 风格指南。完整规则：references/style-overlay.md。

当问题是 “这份文档格式是否规范？” 时加载此技能——而不是 “这份文档是否适合放在这里？”（这属于 doc-diagnostic）。风格审查不会判断文档是否应该存在。它假定文档值得保留，并检查其文字、结构和 Markdown 是否清晰规范。

如何进行审查

分两轮进行。不要交叉进行——架构师对语法违规和风格违规的解读不同，混为一谈会使回复难以理解。

第 1 轮 — 语法（必须修复）

从头到尾检查文件。每发现一项违反语法规范的结构（例如，在应使用 ATX 标题的位置使用 setext 标题、代码块未使用围栏、块级元素周围缺少空行、有序列表使用 ) 而非 . 等），就逐项报告：

Line N:
  Original: <verbatim line(s)>
  Layer:    syntax
  Rule:     <one-line rule from references/syntax-canon.md>
  Rewrite:  <corrected line(s)>
  Apply?    yes / no / adjust

等待架构师回复后再指出下一项。不要批量编辑。语法问题始终先于风格问题。

第 2 轮 — 风格（建议修复）

重新检查文件。每发现一项违反风格叠加规则的情况（例如，使用高于 H2 的标题作为文档标题、篇幅较长的文档未添加 [TOC] 指令、不在例外范围内的正文行超过 80 个字符、使用“这里”等缺乏说明性的链接文本、引用式链接的定义离使用位置很远、多个上级标题下重复使用“摘要”等通用子标题），就按相同格式报告，并标注 Layer: style。

风格审查是建议，不是强制执行。架构师可以不作解释地拒绝任何一项——这些规则带有主观性，并非规范。允许合理异议；标记后继续。

应用已批准的问题

两轮审查完成后，只应用已批准的改写，并在一次 Edit 操作中完成。文件中不得保留审查标记，也不得添加 [reviewed] 标记。差异就是审计记录。

两层规则 — 快速参考

详细规则见 references/。以下摘要涵盖了大多数问题。

语法（必须修正）——快速参考

构造	规则
标题	ATX（#–######），# 后加空格，前后留空行。
段落	用空行分隔。不要缩进。
换行	行尾两个空格「有争议」（参见风格覆盖规则）。优先使用段落分隔。
强调	**粗体**、*斜体*、***两者***。单词中间使用星号（下划线会造成问题）。
引用块	使用 > 前缀；段落之间的空行也加上 >；使用 >> 嵌套。
有序列表	1. 2. 3.（使用句点，不用 )）。从 1 开始。编号可以省略。
无序列表	选择 - / * / + 中的一种，同一列表中不要混用。
嵌套列表内容	缩进 4 个空格（1 个制表符）。列表项内的代码缩进 8 个空格（2 个制表符）。
行内代码	使用一对反引号。代码中含有反引号时，使用一对双反引号。
代码块	使用带语言标签的围栏（```）。缩进代码块也有效，但不建议使用。
分隔线	单独一行使用三个或更多 --- / *** / ___，前后留空行。
链接	[文本](url)。使用 <https://…> 自动链接。引用式链接在其他位置解析。
图片	。始终包含替代文本。
转义	在以下字符前加上 \：`` \ ` * _ { } [ ] < > ( ) # + - . !
行内 HTML	允许使用。块级 HTML 前后留空行。不要缩进标签。

完整规范及示例和已知失效边缘情况：references/syntax-canon.md。

风格（应修正）——快速参考

关注点	规则
H1	只能有一个 H1，用作文档标题。后续标题从 H2 开始。
标题风格	仅使用 ATX 风格。不要使用 setext 下划线。
标题唯一性	避免在多个上级标题下重复使用不带限定词的小标题（“Summary”“Example”）。为其添加前缀。
文档骨架	标题 -> 可选作者 -> 1–3 句简介 -> [TOC] -> ## Topic 章节 -> ## See also。
目录	对无法在一屏笔记本屏幕内显示的文档使用 [TOC]。将其放在简介与第一个 H2 之间。
行长度	80 个字符。例外：链接、表格、标题、代码块。长链接周围的文本仍需换行。
尾随空白	不得有尾随空白。优先使用段落分隔，而不是用两个空格实现换行。
列表	长有序列表使用惰性编号（重复使用 1.）；短且顺序固定的列表使用完整编号。对于一维数据，优先使用列表而非表格。
代码围栏	始终使用围栏（```），不要缩进。始终声明语言。使用 \ 转义 shell 换行。
链接	仓库内链接使用显式的仓库绝对路径（/path/to/page.md），而不是 https://…。避免使用 ../ 路径遍历。
链接文本	应具有描述性。不要使用“here”“link”或裸 URL。
引用式链接	在表格中、URL 影响可读性时，或同一目标出现多次时使用。应在下一个标题前定义。
表格	仅用于便于浏览的二维数据。避免在单元格中写段落。单元格内容不能换行。
图片	尽量少用。始终包含替代文本。
大小写	保留产品／工具／二进制文件的大小写（使用 Markdown，而非 markdown）。
Markdown 中的 HTML	避免使用。大型表格是唯一常见例外。

完整规范及理由：references/style-overlay.md。

路由——此技能不负责的事项

• “这份文档是否应该存在？” -> doc-diagnostic（四问诊断）。
• “这份 ADR 是否诚实？” -> adr-critique（逐行依据“ADR is NOT”检查清单进行审查——这是对内容的审查，而非对形式的审查）。风格审查和 ADR 审查可以针对同一文件运行；先运行 ADR 审查，因为被取代的内容可能导致风格审查工作白费。
• “这份文档应该放在哪里？” -> doc-diagnostic 替代方案目录。
• “这段文字是否易于理解？” -> 不在范围内。此技能规范 Markdown 形式，而非文字清晰度。如果文字不适合其指定受众，建议进行 doc-diagnostic 的受众检查。

此技能不涵盖的内容

此技能仅涉及 Markdown 格式。涵盖标题样式、列表缩进、代码围栏语言标签、链接语法、行长，以及 Markdown-Guide / Google-style-overlay 规则集中的其他内容。此技能不涵盖：

• 行文层面的规范——术语一致性、包容性语言替换、禁用短语、语态 / 时态 / 语气规则。负责这类工作的下一层工具是 Vale（一种行文检查框架，可在 Markdown、AsciiDoc、reST、HTML 等格式上运行可配置的风格包）。Vale 与此技能配合良好：doc-master 修正 Markdown 格式；Vale 规范行文术语。doc-master 不捆绑 Vale 或其规则包。
• AsciiDoc / reStructuredText / org-mode / MDX——此技能仅适用于 Markdown。其他轻量级标记语言各有其规范规则；请使用相应工具（例如 asciidoctor --safe-mode）。
• 拼写和语法——不在范围内。请在使用此技能的同时使用拼写检查器（codespell、hunspell、LanguageTool），而不是用它们替代此技能。

硬性限制

• 此技能只会标记问题，不会批量重写。一次处理一个问题，逐行批准，与 adr-critique 一致。
• 语法问题（“必须修复”）优先于风格问题（“建议修复”）。绝不重新排序。
• 此技能不会凭空制定新规则。每条问题都必须引用 references/syntax-canon.md 或 references/style-overlay.md 中的规则。如果用户对风格问题有异议，则默认听从用户——风格叠加规则带有主观倾向。
• 如果项目本地惯例与规范冲突（例如，项目已统一使用 _下划线_ 强调），此技能会遵循项目惯例。指出冲突；以项目惯例为准。

示例

检查这个 README 的格式——我觉得排版有点乱。 正在加载 Markdown 风格技能。分两轮审查：先检查语法问题（必须修复），再检查风格问题（建议修复），每次处理一个问题并逐行批准。

请提供文件路径（或粘贴内容），我将开始语法检查。

标题下方的 `===` 是有效的 Markdown 吗？ 是的——这是 setext 风格的 H1，属于有效的 Markdown。但风格叠加规则（以及包括 Google 在内的大多数现代风格指南）更推荐 ATX 风格（`# Heading`），因为 setext 下划线“难以维护”，无法扩展到 H2 以上，而且扫描文件时不易看出标题层级。

建议：将 === 替换为单个 #。如果你提供文件路径，我可以进行语法等效的改写（不改变语义）。

我们的文档应该使用什么标题样式？ 此技能默认采用 ATX（`#`、`##`、……、`######`），使用一个 H1 作为文档标题，后续标题从 H2 开始，采用句式大小写，并在标题前后留空行。这与 Google Markdown 风格指南一致。

如果你的项目已有不同惯例（例如，所有标题都从 H1 开始，或顶级标题使用 setext），请告诉我，我会遵循项目惯例。此技能虽有明确倾向，但会服从项目本地规则——指出冲突后继续。

致谢

此技能中的两个层级源自公开可用的风格参考资料：

• 语法规范——根据 Markdown Guide 基本语法参考（https://www.markdownguide.org/basic-syntax/）提炼，采用 CC BY-SA 4.0 许可。请参阅插件根目录下的 NOTICES.md。
• 风格叠加规则——根据 Google 开发者文档 Markdown 风格指南（https://google.github.io/styleguide/docguide/style.html）提炼，该指南属于 google/styleguide（Apache License 2.0）。请参阅 NOTICES.md。

此技能从各个来源提炼了关键规则，并未逐字复现其中任何一份文档。用户需要原文时，请提供链接——不要将大段摘录粘贴到此技能中。