跨平台Markdown避坑指南

提供跨解析器兼容的Markdown编写规范，涵盖空白符陷阱、链接处理、代码块、表格等常见痛点，确保文档可移植性。

基本信息

• 技能名称?Markdown
• 中文名称?跨平台Markdown避坑指南
• 作者?ivangdavila
• 分类?其他
• 版本?1.0.1
• 标签?markdown, documentation, technical-writing, compatibility, formatting, syntax

使用方法

使用说明
核心用法
本Skill是一份 Markdown跨解析器兼容性指南 ，聚焦实际编写中导致渲染差异的陷阱与解决方案。核心围绕六大模块展开：

1. Whitespace Traps（空白符陷阱） ：强调列表、代码块、引用块前必须空行；嵌套列表需4空格而非2空格；避免用双空格换行；清理行尾空格。
2. Links & Images（链接与图片） ：处理URL中的括号和空格（使用百分号编码或尖括号包裹）；提醒引用式链接可能静默失败；强制要求图片alt文本。
3. Code（代码） ：解决反引号嵌套问题（4+反引号外层围栏或双反引号包裹）；语言标识对语法高亮的影响。
4. Tables（表格） ：列对齐语法（ ---: , :--- , :---: ）；管道符转义；禁止表格前空行；空单元格占位。
5. Escaping（转义） ：列出文本中需转义的特殊字符；代码区域内无需转义。
6. Portability（可移植性） ：优先纯Markdown而非HTML；扩展语法（脚注、任务列表等）需确认目标解析器支持；YAML frontmatter的放置规范。
   显著优点
   问题驱动 ：每个要点对应真实渲染故障案例，实用性强
   覆盖主流解析器 ：兼顾GitHub Flavored Markdown与CommonMark严格实现
   细节精确 ：如4空格vs2空格、双空格换行被编辑器剥离等，减少调试成本
   潜在缺点/局限性
   非完整教程 ：假设用户已了解Markdown基础，仅聚焦"坑点"
   无自动化检测 ：纯文档型Skill，无工具辅助验证
   扩展语法覆盖有限 ：未深入Mermaid、数学公式等现代扩展
   版本漂移风险 ：解析器行为可能更新，建议需定期校验
   适合人群
   技术文档工程师、开源项目维护者、需要确保README/文档在多平台（GitHub/GitLab/静态站点生成器）一致渲染的开发者。
   常规风险
   内容本身为规范文档，无执行风险；但若用户依赖其中建议而目标解析器未明确遵循CommonMark，仍可能出现预期外渲染差异。