菜单

为什么不应该使用Markdown来写文档

2018-03-19 - 优秀原创

Python部落(python.freelycode.com)组织翻译,禁止转载,欢迎转发。

Markdown是互联网上最普遍使用的轻量级标记语言。对于写博客和评论这类的任务,用Markdown很棒。不过最近技术社区的人员开始用它来写文档。

 

下面我列出一些反对使用Markdown的观点,希望能帮助你决定是否适合使用Markdown。如果你在考虑使用Markdown,我希望你也可以关注下Asciidoctor 和Sphinx,我发现用它们写文档更好。

 

人们选择Markdown是因为它可以很简单的处理一些基本任务。开发者选择它是因为GitHub支持它,尽管GitHub支持9种不同的标记语言,包括 Asciidoc和reStructuredText。但是当文档从几页逐渐增长到大的文档集,Markdown很快就崩溃并成为累赘。下面是这种情况发生的原因。

 

缺乏一个标准

最初,Markdown是由John Gruber写的initial implementation来定义,但并未明确规定行为规范。

 

随着Markdown越来越流行,越来越多的站点开始支持Markdown的实现,这些站点是用其它语言写成的,因此产生了更多的Markdown实现。所有这些实现有轻微差别,但都达不到令人接受的程度。

 

比如有些实现要求开头有一个空格,但另外的一些不做要求:

 

还有一些小问题使得Markdown很难在不同的站点和版本之间移植

在过去的几年里,Commonmark已经发展成标准化的Markdown。这很好,应该解决很多问题,但是却没人采用它。

 

风格

Markdown缺乏采用的主要原因是这些年来其一直在变化。起初,Markdown功能很有限,每当有流行的工具在Markdown上实现的时候,都会有一个特定的风格。听起来不错 ,是吧?问题是每一个工具都形成了不同的风格,甚至连实现相似任务的工具都有不同的语法。

 

举个例子,在Markdown Extra 中代码块是下面这种样式:

这将python类应用于输出的HTML块

 

然而,同样的情况在GitHub Flavored Markdown 中是这样的:

这会将语法高亮显示应用于实际呈现的HTML输出。

相似的概念,不同的语法,但都是Markdown。

 

缺乏扩展

其它的标记语言,可以对其进行扩展以提供需要的功能。它们在语法上有增添新功能同时又不会违反初始规范的机制。

比如reStructuredText,具有内嵌和块级别的标记:

可以了解更多关于 rfc, class和 contents的概念。

 

作为一个使用rST或Asciidoctor的开发者,我可以以一种简单,可插入的方式增添新的标记。

我不必改变语言的解析方式,而且我还可以通过标准扩展机制向其它用户分享那些新功能。

在不同的版本间进行移植这些功能,用Markdown可办不到。

注意:CommonMark正在开发可扩展性的语法,但还没有实现。

 

缺乏语义化

尽管很多人添加了很多扩展,但都不够语义化。这意味着不能写Class或Warning,只能写文本。因此很多人直接将HTML嵌入到Markdown中:

而在reStructuredText中,你可以写成:

这在HTML,PDF,甚至任何创建的输出格式中都可以合适的显示为一个Warning.

 

语义化标记可以将所写的文字与它们的显示方式完全分开。

 

缺乏语义化将导致问题,原因如下:

  • 现在Markdown依赖于显示中的特定CSS类,这意味着编写者必须考虑如何设计页面。
  • 内容不可再移植到其他输出格式(PDF等)。
  • 转换到其他标记工具和页面设计变得更加困难。

注意:

在我的博文Semantic Meaning in Authoring Documentation中有关于语义化更详细的介绍。

 

锁定和缺乏可移植性

风格的多种多样及缺乏语义化导致锁定。一旦创建了大的Markdown文档集,就很难将它们迁移到另一个工具上,即使该工具宣称支持Markdown!自定义的HTML类和奇怪风格的扩展组成的文档集,除了在当前的工具和设计外,在其它地方都行不通。

 

同时也无法轻易将Markdown迁移到其他标记语言(Asciidoc或RST),因为Pandoc和其他转换工具不支持您风格的扩展。

很多人选择Markdown是因为他们认为他们可以在稍后迁移到其他工具或其它标记语言。

Markdown绝对是最低的共同标准,除非文档集足够小,否则你所需要的东西都不在基本语法中。

任何有意义的文档都需要扩展,而一旦使用Markdown各种各样风格的扩展,你将失去所有可移植性的优势。

 

结论

我认为CommonMark是向前迈出的一大步,如果它被更广泛地使用,并且增加对扩展的支持,我会全心全意地推荐它作为解决这个问题的方法。我不能拥护Markdown目前的生态系统,并且我认为它很大程度上阻止了人们使文档变得更好。

 

我希望我们可以开始推进更加标准化的语言集合,包括CommonMark,reStructuredText和Asciidoc,在我们使用的工具套件中全面支持他们。目前,Sphinx和Asciidoctor是很好的替代品。它们语音内部内置了更多的扩展,并且含有用于构建当今文档更完整的工具。

 

Markdown更像是一个概念,而不是实现。 它通常意味着“在看起来与Markdown类似的语言上的一组互不兼容的扩展”。 当创建大的文档集时,它显然不是正确的工具。

披露:我从事的一款产品,Read the Docs,是基于Sphinx的,所以我的观点可能有偏颇。

 

 

英文原文:http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
译者:Chris

转载请注明: 转载自—艾瑞可erik

本文链接地址: http://erik.xyz/1426.html

发表评论