Markdown

空白符陷阱

• 列表、代码块和块引用前需要空行——否则，许多解析器会将其视为前一段落的延续
• 嵌套列表在GitHub/CommonMark中需要4个空格（而非2个）；2个空格会在严格解析器中破坏嵌套结构
• 两个尾部空格用于<br>换行——这种方式不可见且常被编辑器删除；建议改用空行或<br>标签
• 仅含空格的行仍会切断段落——需修剪尾部空白符

链接与图片

• URL中的括号会破坏[文本](网址)结构——应使用%28 %29或尖括号语法：[文本](<含括号的网址>)
• URL中的空格需要转换为%20或使用尖括号语法
• 引用式链接[文本][引用标识]静默失败，如果[参考]: 网址缺失——请验证所有参考是否存在
• 图片若无替代文本：务必提供![替代文本](网址)即使为空![]()以便辅助技术工具使用

代码

• 围栏代码块内的三重反引号——外层围栏使用四个或更多反引号，或采用缩进方法
• 包含反引号的行内代码——用双反引号包裹并留出空格：`` `代码` ``
• 围栏后的语言提示影响语法高亮——仅在纯文本时省略

表格

• 对齐冒号置于分隔行：:---左对齐，:---:居中对齐，---:右对齐
• 竖线|单元格内容中需要反斜杠转义：\|
• 表格前不能有空行——有些解析器会出错
• 空单元格至少需要一个空格，否则无法渲染

转义

• 文本中需要转义的字符：\*,\_,\[,\],\#,\>,\``,\`
• 在代码段/代码块内无需转义
• "&"符号仅在可能形成HTML实体时需要转义为& 可移植性

Portability

• HTML标签在GitHub上有效，但在许多渲染器中会被剥离——建议优先使用纯Markdown
• 扩展语法（脚注、任务列表、表情符号短代码）并非通用——请检查目标解析器
• YAML前置元数据需要---代码围栏且仅能置于文件开头；部分解析器会将其渲染为普通文本