该技能聚焦于生成干净、可移植、能在多种解析器中正确渲染的 Markdown,核心目标是规避不同解析器之间的差异。资料以注意事项形式列出常见陷阱。
空格方面:列表、代码块和引用块前需要空行,否则不少解析器会将其并入上一段;嵌套列表在 GitHub/CommonMark 中需要 4 个空格而非 2 个,严格解析器下 2 个空格会破坏嵌套;行尾两个空格可实现换行但不可见且常被编辑器清除,更推荐空行或 br 标签;仅含空格的行仍会打断段落,应去除行尾空白。
链接与图片方面:URL 中的圆括号会破坏 text,可用 %28 %29 或尖括号包裹;URL 中的空格需用 %20 或尖括号语法;引用式链接 [text][ref] 在缺失 [ref]: url 时会静默失败,应核对引用是否存在;图片始终提供 alt 文本,即使为空。
代码方面:围栏代码块内部出现三重反引号时,外层应使用 4 个及以上反引号或采用缩进方式;行内代码包含反引号时,用双反引号并加空格包裹;围栏后的语言提示影响语法高亮,仅在确为纯文本时省略。
表格方面:对齐冒号写在分隔行中;单元格内容中的竖线需用反斜杠转义;表格前不要留空行;空单元格至少需要一个空格。
转义方面:正文中需转义的字符包括星号、下划线、方括号、井号、大于号与反引号;代码段与代码块内无需转义;和号仅在可能构成 HTML 实体时需写成 &。
可移植性方面:HTML 标签在 GitHub 可用但许多渲染器会剥离,优先使用纯 Markdown;扩展语法(脚注、任务列表、emoji 短代码)并非通用,需确认目标解析器;YAML frontmatter 需要 --- 围栏且只能位于文件开头,部分解析器会将其渲染为文本。除上述内容外,该技能的安装与调用方式暂未提供。