markdown中#替代_Markdown与替代软件文档

markdown中#替代

如果软件项目的任何一个方面经常被跳过，那就是文档。从长远来看，无证软件是无法使用的软件。问题是，编写软件文档可能是一件繁琐的工作，尤其是在涉及复杂的格式设置时：目录，脚注，尾注，超链接等。

曾几何时，记录项目的典型方法是编写HTML。但是出现了一个更好的方法：使用易于以原始格式阅读但可以快速呈现以生成复杂标记的文本格式。

为了满足这种需求，已经开发了几种不同的文本格式-有些来自博客区，有些来自更正式的软件开发圈子。在这里，我们将了解四种最常见的格式，它们的优缺点以及它们最适合的项目类型。

降价促销

从那时起，Markdown已成为许多场所中从文本到富文本格式的事实上的标准。例如，GitHub 使用Markdown的变体在问题注释中添加样式。

Markdown最初是为博客而设计的。它易于键入和记忆，但缺乏更复杂的文档所需的灵活性。

Markdown专家

Markdown的最大好处是易于采用，广泛使用和广泛支持。 Markdown文档可以按原样阅读，而无需呈现为HTML，并且仍然可以理解。大部分基本格式（重点，标题，超链接等）都可以在几分钟内学习到，并且备有很多备忘单，以带您了解更高级的概念。

降价利弊

这导致Markdown的另一个大缺点：它是事实上的标准。您从Markdown获得什么样的行为完全取决于实现。最终结果是一家冰淇淋店的Markdown“风味”物有所值，其中许多风味彼此微妙地不相容。如果每个人都同意使用完全相同的工具来生成和处理Markdown，这并不是很糟糕，但是对于规模较大的项目而言，这很难实施。

解决此难题的一种可能方案是Markdown的一个分支，称为Commonmark ，它试图使Markdown标准化并消除其歧义。 Markdown的某些实现现在使用Commonmark规范，同时添加了自己的自定义更改。例如，GitHub Flavored Markdown具有诸如任务列表项之类的元素的扩展。但是，其他流行的变体（例如Pandoc文档生成工具使用的Pandoc Markdown）不遵循Commonmark。

降价用例

由于这些限制，Markdown最好用于不需要大量文档的较小项目，例如，创建一个运行几个屏幕的自述文件，或者记录一个只有几个调用的API。对于更苛刻的要求，Markdown可能无法扩展。

reStructuredText

像Markdown一样，reStructuredText（简称“ reST”）使用简单的内联标记来允许将纯文本呈现为HTML，同时保持原始文本的高度可读性。 reST格式最初是为了帮助记录Python 区中所做的工作而开发的。它是从Zope项目完成的工作中发展而来的，它的第一个正式版本是2002年与Python一起发布的。

reStructuredText或reST不会比Markdown复杂得多，但是可以提供更多的格式化功能。

reStructuredText的优点

开箱即用，reST提供了比Markdown更多的标记支持。例如，表格并不是Markdown规范的正式组成部分。尽管第三方在Markdown中增加了对表格的支持，但不能保证Markdown的任何特定实现都会支持它们。相比之下，reST支持开箱即用的表格格式。

此外，默认情况下，reST支持许多其他有用的文档元素，包括脚注，引文和目录。 reST有一个核心规范，这意味着关于reST实现应如何表现的唯一真理。该规范的一种实际实现是Docutils项目。

与Markdown相比，reST的另一个主要优势是对附加功能的内置支持。如果给定的reST实现要修改语法，则可以在保留核心reST功能的同时进行修改。例如， Sphinx文档工具以这种方式建立在reST上。

reStructuredText缺点

如果您当前是Markdown用户，并且要切换到reST，请提前警告：许多reST格式语法与Markdown的语法都不一样。例如，Markdown中的文字块在块的上方和下方都有三个反引。在休息，文字块开始与双冒（在块之前的线的端部），并且需要缩进或引用被分开设置。此外，许多reST语法元素都是空格敏感的，这是该项目起源于Python 区的标志。但是，如果您没有Markdown的投资或经验，那么这些差异就不会成为问题。

reStructuredText用例

对于那些Markdown规模过大且长期需要更强大功能集的项目，使用reST是明智的选择。可以通过Pandoc之类的工具将现有的Markdown文本转换为reST。

阿西多克

Asciidoc最初于2002年在Python 区中开发。像reStructuredText一样，Aciidoc也采用Markdown的可读标记概念，并将其扩展为解决更多用例。虽然基本格式语法（粗体，斜体等）类似于Markdown，但Asciidoc包括开箱即用的软件项目中通常使用的复杂格式功能。

Asciidoc比reST或Markdown更为冗长，但是其块元素结构允许对打印和在线文档进行高度灵活的格式化。

Asciidoc专业人士

属性的另一个强大的Asciidoc功能。属性允许开发人员创建名称/值对，本质上是变量，并为它们分配块级别或内联。将此与插件或附件结合使用，可以扩展Asciidoc以解决各种自定义方案。

Asciidoc的工具集还旨在支持比数字文档更多的功能。如O’Reilly Atlas平台所使用的，它可以用于导出印刷书籍的版式。

杀虫剂

Asciidoc的最大缺点是缺少对Asciidoc规范的单独定义-一种可以重新实现的独立形式语法。 Asciidoctor，最常用的Asciidoc工具，通常被视为Asciidoc的参考实现。但是，尝试为Asciidoc创建单独的正式规范并没有产生任何有用的结果。

Asciidoc用例

由于其强大的输出和内部文档结构功能，如果您要创建将经受多种考验的文档，例如，如果您计划从文件中生成印刷文档，或者为您打开文件的大门，Asciidoc是最佳选择。其他格式。其他格式也可以实现这些功能，但是Asciidoc的功能和工具链（ Asciidoctor应用程序）已经在这些用例中大放异彩。

组织模式

组织模式主要设计用于个人组织和项目跟踪，而不是复杂的文档。

组织模式专家

组织模式具有与Markdown相同的许多优势。它易于学习，易于使用，并且可以使源文本非常容易用肉眼阅读。

Org-mode的大多数格式化功能都围绕任务或计划安排，例如要做的事情列表，为任务定时进出，制定议程以及格式化表格中的文本。

组织模式缺点

至少对于那些不熟悉Emacs的人来说，Org-mode的最大缺点可能是对Emacs密钥绑定的严重依赖。按键绑定使您能够以最少的击键次数完成许多常见任务。但是，如果您还不习惯在Emacs中使用这种工作方式，则学习曲线可能会令人望而却步。您可能需要一段时间才能感到有成效。

另一个缺点是Org-mode没有形式语法。规范的实现是Emacs软件包。确实存在Org-mode语法的草稿版本，但与Asciidoc的草稿版本一样，它不过是草稿而已。

最后，与Markdown，reStructuredText和Asciidoc不同，大多数组织模式的实现都没有实时预览的形式。 Emacs通过附加的次要模式org-preview-html-mode填补了这一空白，该模式通过在微型浏览器中将其呈现为HTML来自动预览保存的文件。但是其他组织模式实现（例如为Microsoft Visual Studio Code创建的实现）还没有。

组织模式用例

由于组织模式主要面向任务，因此它不适用于公共文档。最好是由几个人使用的内部文档来跟踪进度或共享有关团队工作的信息，并使用最小的，相互共享的工具集（例如Emacs）来执行此操作。

翻译自: https://www.infoworld.com/article/3336202/markdown-vs-alternatives-for-software-documentation.html