Markdown的一些操作小技巧
Published:
0x01 章节定位符
许多 Markdown 处理器支持标题的自定义ID，部分 Markdown 渲染器会自动添加它们。
添加自定义 ID 可以允许直接链接到标题并使用 CSS 对其进行修改。
要添加自定义标题ID，与标题相同的行上用大括号括起该自定义ID {#user_defined_id}。
0x02 图片样式规范
使用 Markdown 插入图片一般有两种方式
- Markdown 原生语法
![]() - HTML 的
<img>和<figure>标签
但是前者无法定义图片大小和图片解释词，所以最好使用 HTML 进行标定。
修改图片大小
<img src="/images/rocks.jpg" width="200" height="100">为图片添加注释
<figure style="text-align: center;"> <img src="/images/20210802/netfilter.png" alt="20210802" width="500" height="150"> <figcaption>A Netfilter Demo Pic</figcaption> </figure>实际效果如下
A Netfilter Demo Pic
在 Markdown 中使用 HTML 的最佳实践
- 使用语义化的 HTML 标签
- 添加样式增强
- 确保内容的可访问性
- 保持代码整洁和可维护
0x03 使用 FrontMatter
Front Matter 是位于文件顶部、用分隔符包围的元数据区块，用于存储文档的元信息。
很多静态网站生成器都支持 Front Matter：
- Jekyll (Ruby)
- Hugo (Go) - 支持 YAML、TOML、JSON 格式
- Next.js (React/JavaScript)
- Hexo (Node.js)
- GitBook
使用过程中，最佳实践是在分隔符后保持一行空行。
- 分行可以从而保持更好的可读性，清晰区分元数据和内容。
- 避免解析问题，例如在 Jekyll 中紧接
---的内容会被认为是 FrontMatter 的一部分，并引发渲染错误。 - 符合 CommonMark 标准：空行有助于 Markdown 解析器正确识别段落。
0x04 使用 Mermaid 绘图
Github Page 虽然可以支持 Mermaid 渲染，Jeklly 也可以支持 Mermaid 插件。
但在 Jeklly 主题渲染出来 Github Page 中使用 Mermaid 时，就可能会被屏蔽，或不能正常显示。
所以不用尝试使用 .gem 文件中引入 Mermaid 的 Gem 插件。
Minimal Mistake 的 Repo 中的 issue-4617 也提到了 Mermaid 通过插件的无法引入问题。
唯一的解决方案就是使用用户自定义 js 脚本在页面中使用 Mermaid API 渲染。
在 header 中添加用户自定义脚本
<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js"></script>
然后在页面 footer 中添加脚本函数，用于渲染 Mermaid：
<script>
var config = {
startOnLoad:true,
theme: 'forest',
flowchart:{
useMaxWidth:false,
htmlLabels:true
}
};
mermaid.initialize(config);
window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
</script>
这样既可以避免在 Markdown 中混用 html 标签定义 Mermaid 导致的非正常显示，同时还有助于降低后续文档迁移的难度。
更为复杂和完备的支持脚本可以参考：Mermaid JS Support for Minimal Mistakes。
0x05 开启文章目录
0x06 本地测试
https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll