写 Docs 人们实际上享受阅读 Markdown 到处都是: READMEs, wikis, API docs, 甚至内部备忘录.
但我所看到的大多是简单和未充分利用的。
经过多年的写作和保存文献,我收集了几道技巧,使这些技巧更加可读和可维护.
比较时使用表格,而非布局表对于结构化数据来说是很大的,但人们滥用它们来进行布局.
保留它们进行实际比较:选项,版本,参数.
这样就很干净 很容易扫描 不要用表格来强迫两栏布局;这就是HTML的目的,也不值得痛苦.
带有语言标记的栅栏码块总是指定语言.
它给予语法突出效果,并帮助屏幕阅读器. javascript const greating = "你好"; 标记下用于纯输出,用于 shell 命令,以及更改.
取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取来取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取 可选内容可折叠部分长文件掩埋核心 。
在相撞区段(GitHub和许多平台上的工作)中环绕可选细节. yaml版本: 2 yaml 读者可以跳过它而不从一面文字的墙上滚动.
导航长文件的锁定链接需要一个目录 。
从标题上标记出自动生成主锚,但可能无法预测.
设置明确的ID 安全。
然后链接到他们: 这在GitHub,GitLab,以及大多数静态站点发电机上工作.
Callouts 的块名使用块名来突出警告、提示和注释。
它们在视线上突出,没有断流。
一些渲染器支持自定义标签,如(GitHub),但平面粗体文本在任何地方都有效.
摆脱强调问题 在写代码时,下划线可以触发斜体.
如果你在写一个像...
的文件名, 把它包起来, 或者避开下划线。
后ick更清净.
使用定义列表( 当支持时) 一些 Markdown 口味( 如 Pandoc) 支持定义列表 。
它们很适合名词或解释术语.
如果您的平台不支持它们,请倒回表格或粗体文本.
将行长合理的硬包装行保持为80-100个字符.
这使得diffs更清洁和编辑更方便.
大多数编辑器可以自动做到这一点.
对于维护者的评论 使用 HTML 注释为未来不会在输出中显示的编辑者留下注释 。
这对医生们来说是宝贵的 最终的思考马克当很简单,但一些刻意的选择却有很大的改变.
挑出适合你平台的花招 和他们在一起 你的未来和读者会感谢你的.