SuperAPI AI 工具集

markdown-style

设计与创作

查看项目

更新于 10-15 23:42

技能介绍

用途:审查、lint 或修正 Markdown 文件的格式,适用于 README、ADR、runbook、how-to、设计文档等任意 .md 文件。它只判断文档格式是否规范,不判断文档是否应该存在。

主要能力:分两层规则。语法规范(syntax canon)定义合法 Markdown 写法,源自 Markdown Guide 基础语法;风格叠加(style overlay)是审查者额外执行的偏好规则,源自 Google Markdown 风格指南。完整规则见 references/syntax-canon.md 与 references/style-overlay.md。

使用方式:分两轮执行,不可交错。第一轮语法(必须修复),自上而下逐条输出发现,格式为行号、原文、层级、规则、改写、是否应用,等待确认后再报下一条,不做批量修改。第二轮风格(建议修复),同样逐条输出,Layer 标为 style,用户可无理由拒绝。两轮完成后,仅对已批准的改写做一次 Edit。

语法要点:标题用 ATX(#–######),# 后加空格,前后留空行;段落间空行且不缩进;强调用 粗体、斜体;有序列表用 1. 2. 3. 且从 1 开始;无序列表在 - / * / + 中选一种且不混用;嵌套内容缩进 4 空格,列表内代码缩进 8 空格;行内代码用单反引号;代码块用围栏并标语言;链接用 text;图片必须含 alt 文本。

风格要点:恰好一个 H1 作标题,后续从 H2 开始;仅用 ATX;避免多个父级下重复裸子标题;文档骨架为标题、可选作者、1–3 句简介、[TOC]、主题章节、See also;超过一屏的文档用 [TOC];行宽 80 字符(链接、表格、标题、代码块例外);无行尾空白;代码块始终围栏并声明语言;仓库内链接用绝对路径;链接文字要有信息量,不用 here;表格仅用于二维可扫描数据;保留产品名大小写(Markdown 而非 markdown);避免内联 HTML。

限制:只处理 Markdown 形式,不负责文档是否该存在、ADR 内容是否诚实、文档归属或文字可读性;不覆盖术语一致性、包容性语言、禁用短语等散文层规则(可配合 Vale);不支持 AsciiDoc、reStructuredText、org-mode、MDX;不含拼写与语法检查。它只标记发现,不批量重写;语法发现优先于风格发现;不发明新规则,每条发现须引用规则文件;与项目本地约定冲突时遵从项目。资料未提供安装命令、收费或平台信息。