你用嵌套的项目符号点、几个代码块和一个比较两种方法的表格写README。它在你的编辑器中的纯文本中看起来很好。然后你将其推送到GitHub,表格对齐错误、你的一个代码块没有正确关闭、编号列表因为杂乱的空行而在中途重新开始为1。现在你推送小修复提交仅仅是为了让格式正确。
Markdown足够简单,用于从内存中的基本格式书写,但表、嵌套列表和代码围栏都有小的语法怪癖,在渲染器之间略有不同。GitHub Flavored Markdown与CommonMark不同,与你的静态站点生成器使用的不同。"在我的头脑中看起来正确"与"在页面上呈现正确"之间的差距是实时预览赚取其保留的地方。
为什么提交来检查是坏工作流程
推送提交仅仅看README如何呈现,然后推送另一个来修复破坏的表,然后另一个来修复修复,用与实际内容无关的格式噪声混淆了你的提交历史。它也意味着每个预览循环需要与推送和页面重新加载一样长 — 足够慢,你停止费力检查,只是希望它看起来很好。
看到呈现的输出当你键入时
Bellows包括一个Markdown预览工具,当你粘贴或键入原始Markdown时呈现格式化的输出。头部、列表、表、链接和代码块都立即呈现,所以你可以在它们最终进入提交之前捕获格式化错误。
编写README和PR描述
拉取请求描述和README文件通常是审查人员或新贡献者首先读的东西。在你提交之前检查头部、清单和链接图像呈现正确会节省一轮"能你修复格式化"评论。
脱机起草文档
在飞行中或在网络不可靠的地区编写文档不意味着放弃看到你的格式化正确呈现。本地预览工具的工作方式相同,不管你是否连接。