使用 Markdown 注意事项

发表于 更新于

分为语法和工具两个部分，备忘录。

语法

写在前面

在使用 JotterPad（CommonMark）阅读 markdown 格式的文本时，发现的细节：

  1. 标题 # 后需要有空格，才能解析成标题，不然就是文本；【重要】

    • 进一步修正：任意级别的标题行前后添加空行，至少标题行之前要有空行，# 之后添加空格；

  2. 使用参考式链接时，链接网址只能放在文件最末尾，不然识别不出来；【重要】

  3. 引用内使用编号问题：

    引用文字

    1. item1
    2. item

    编号结束，结尾的引用文字

  4. 怎么写代码块？——是解析的，只不过呈现方式只体现在字体上，排版效果并不明显。

  5. 尽量不要嵌套使用。在 GitHub 上项目的 README.md 都不复杂。占一屏幕，不需要滚屏。 建议很值得采纳，但实在是不实用。

  6. 可以做图片链接的哦，惊喜

  7. 嵌套时无需有空行（分段需求除外，比如引用时），当两个模块是平行关系时需要有空行（列表除外，列表项之间添加空行会引入 <p>）。参考 1.1 节

  8. 中英文混合排版加不加空格问题，持保留态度，无论加或者不加，都保持原状。

    1. 强调语义，不加；强调呈现，添加。
    2. 书写笔记不考虑纯手工补充空格，为了表现效果美观吹毛求疵，时间成本太高，没有意义。【重要】

    扩展阅读：

  9. 测试 item

块元素

模块之间的嵌套使用，怎么书写是规范的一直是一件比较困惑的事情。但在我写下这篇文字的时候，我已经感觉到胜利在朝我招手了。

首先一定要有意识区分“块元素（Block Element）”和“Span Element”，对于熟悉 html 的程序员来说可能是很 easy 的一件事情，但是虽然我用 Markdown 两三个月，相关的操作手册、语法说明也看了很多，但我是自动过滤这两个单词的，讲解标题（用不同数目的 # 区分标题级别）和强调（用 * 斜体，** 加粗）时肯定是分别放在 Block Element 和 Span Element 中介绍，但我脑子里是没有这两个概念的，我并未意识到它们意味着什么，甚至并未意识到它们的存在。我真的是个前端白痴，原谅我。

  1. 块元素（Block Element）包括：

    • 标题
    • 引用
    • 列表，注意是整个列表，而不是列表的 item
    • 代码块
    • 分割线

  2. Span Element 包括：

    • 链接
    • 强调
    • 代码
    • 图片

块元素是涉及嵌套的主体！Span Element 不是。所以嵌套问题是块元素的嵌套问题，额，如果我了解 html 多好。

结论（针对 GFM）

秘籍：（在严格坚持第一点的基础上，除却以下情况不会用到第二点：如果问题出现在章节末尾（见本文末尾）、列表末尾，使用第二点）

  1. 每个独立的块元素（包括分段）之后留有空行，标题、分割线可以除外；

  2. 哪个块元素解析有问题，就在哪个块元素之前加空行；

    1. 为了保证一致性（特殊情形，即当前嵌套情形（列表主体除末尾空行无其他空行，且在末尾嵌套有子列表）），要求嵌套子列表时，子模块前添加空行（即本行之前的空行，否则解释时不完美）；

  3. 综合上述两点，在每个块元素（包括分段）的前后添加空行可以保证所有情形下解释正确。唯一的不足在于阅读源文本时可能稍显松散。

  4. 其实，在每个块元素（包括分段、标题、分割线）之前留有空行是不是就万事大吉了呢？【重要】

详细描述：

  1. 分段用空行，这句是废话；

  2. 标题之前加空行，保证所有情况下语法正常解释；【重要】

    • 如果前置标题、分割线或者普通段落，则没有空行语法也能正常解释；
    • 如果前置列表、引用等，没有空行，语法解释后呈现有问题；

  3. 空行意味着引用、列表的结束；标题、分割线是单行的；GFM 中代码块是 ``` 结束的。多个空行合并成一个。

    • 分段时，空行意味着段落的结束；
    • 非分段情况下，段落之后不用跟空行。接标题、引用、列表、代码块都意味着段落结束。
    • 非分段情况下，段落之后无空行直接跟有序列表，是有问题的；直接跟无序列表没问题；
    • 综合上述三条，建议每个独立的块元素之后留有空行，标题、分割线除外【重要】

  4. 列表内容拥有缩进概念；

    • 列表 item 中缩进内容（针对引用、代码块）前（或者后）加空行；否则语法无法正常解释
    • 缩进内容为列表（即嵌套子列表）时，按照规则建议添加空行。即使无空行，语法也能正常解释，看着还顺眼一点
    • 综合上述两条，建议在嵌套子模块的结尾留有空行【重要】

补充说明：

  1. 列表的 item 之间一般不需要空行（分段除外），如果

    如果列表项之间有空行，markdown会给每一个生成的li元素创建一个p:

工具

前两年一直使用的 MarkdownPad2，后来随着系统更新（而软件并未跟进）出现了几项功能性问题，虽然也能通过某些手段结局，但无疑是影响体验的。

MarkdownPad 2 使用问题

在此基础上，由于对 Visual Studio Code 好奇心（喜新厌旧嘛），放弃了使用 MarkdownPad2，但回头再看（2020/12/25 17:38:28 ）前者也只那些 vimer 的狂欢，经过各种调教之后可能好用，但调教本身也是成本。

快捷键支持并不完全。还是算了。来源

深有感触，不胜其烦。所以又回归了 MarkdownPad2