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

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

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

缺乏一个标准

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

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

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

# Heading 1

#Heading 1

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

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

风格

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

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

~~~ .python
import antigravity
~~~

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

然而，同样的情况在GitHub Flavored Markdown 中是这样的：

```python
import antigravity
```

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

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

缺乏扩展

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

比如reStructuredText，具有内嵌和块级别的标记：

.. contents:: All the stuff I'm going to talk about
   :depth: 2

Please look at :rfc:`1984` for more information.
This is implemented in our codebase at :class:`Example.Encryption`.

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

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

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

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

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

缺乏语义化

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

而在reStructuredText中，你可以写成：

<div class="warning">
This is a Warning!
</div>

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

.. warning:: This is a 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类似的语言上的一组互不兼容的扩展”。 当创建大的文档集时，它显然不是正确的工具。

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