Markdown的写作技巧与规范

写在前面

最近用 vscode 写 markdown , 发现语法提示说一篇 markdown 文章只能有一个一级标题, 这让我非常意外, 因为之前一直都是用好多一级标题区分文章的段落的, 后来我在 jekyll 上看到了自己的文章, 一级标题跟题目一样大, 才意识到自己这么多年原来都写错了…

这个发现让我决定好好规范一下博客的写作, 特别是一些看起来不重要的地方, 比如标题选取.

这里面有的规范只是对我的 jekyll 博客来说的, 因为这个博客有些限制, 例如 liquid 语法规定了双大括号不能连续, 会被解析为 liquid, 这时候 github 的解析器报错, 博客内容就没法更新了.

关于标题

1. 一篇 markdown 只能有一个一级标题.

特殊情况

这里主要说一下 jekyll 的一些限制.

1. 连续的两个大括号, 例如: {{

   需要用注释语法包裹, 之前吃过好几次这个亏 {% raw %} 出现过{{ }}的内容 {% endraw %}

2. 数学公式, 这里特指行间公式, 在双美元符号的前面和后面都要空行, 否则解析会把前后的内容连起来.

3. 复制来的超链接, 如果里面有 | 符号, 需要加反斜杠转义, 否则会被当成表格, 比较坑的点.