Markdown Tricks for Clean Docs 我写了很多文件 这些年来, 我了解到Markdown比大多数人的功劳更大。
除了标题、粗体和链接等基本内容之外, 还有一些使我的文件更清洁、更可读、更易维护的技巧。
我经常用这些 使用表格 Wisely Tables 对结构化数据来说是很棒的,但它们会变得混乱.
关键是保持它们简单,并配合管子的可读性,尽管你不必完美地配合它们来让Markdown渲染.
然而,调整它们使得源头更容易被扫描.
我也避免使用表格来进行复杂的布局;它们最适合比较或参考数据.
进展跟踪任务清单是跟踪文件,特别是READMEs或项目计划中进展的救命工具。
它们很简单:用于不受限制和检查。
许多平台以复选框来制作它们,使其具有交互性.
可折叠的分科 长文件可以吓人。
可折叠的部分让你隐藏细节,直到读者需要它们.
这在GitHub和许多其他平台上都起作用.
使用 HTML 标记 。
打Npm 安装我的包装标记 注意内容后和之前的空白行;这是正确渲染所需的.
导航的锁定链接 如果您的博士长, 锁定链接会帮助读者跳转到特定的章节 。
大多数Markdown处理器会自动从标题生成锚.
您可以使用它们链接( 空格被连字符和小写所取代) 。
例如,将链接到一个名为"安装步骤"的章节.
您也可以使用 HTML 添加自定义锚点, 但我很少需要, 除非标题文本是不寻常的 。
带有语法加亮的代码块总是指定代码块的语言.
它能提高可读性,并有助于语法突出.
但有一个把戏:您也可以使用栅栏内部添加标题或文件名.
这在许多平台如GitHub和GitLab上得到了支持.
你好, ${name} !` ;} 一些平台支持特殊的提醒语法,比如GitHub的和.,这些语法用有色相框来渲染.
使用这些如果有。
逃出字符 有时你需要从字面上显示Markdown字符.
用回鞭来躲避他们.
例如,如果显示星号而不使其大胆,则写作.
写Markdown本身时很方便 被嵌入的列表 被嵌入的列表可能很棘手 因为缩进很重要 使用两个或四个空格( 一致) 来创建子项 。
我更喜欢四个空间来澄清 横向规则 横向规则()对于不使用标题而将各科分开是很好的。
取出清净相相相相.
只要确保前后添加一行空白来避免将其变成一个标题(就像文本后正行上).
内部 Docs 使用相对链接 在repo中连接文件时,使用相对链接而不是绝对URL.
这使得你的文档可以手提和容易移动。
例如,代替.
这是一个小的习惯, 回报很大 当你重组你的项目。
最后保持简单,最好的技巧就是不要过度使用这些特性.
Markdown的意思是用纯文本读取.
如果你发现自己筑巢过多的块状引号或者使用表格来进行布局,请退后并简化.
干净的道克是关于清晰的,而不是展示每个特征.
这些花招使我的文件更容易维护,更方便用户使用。
试试看哪个为你的工作流程工作.