Markdown对于简短的文档（例如readme.md）是可以容忍的。除此之外，它不是好的工作工具。
Markdown只是一种编写更简单，外观漂亮的HTML的方法。这就是人们使用它的原因：它很容易学习，并且很容易用任何一种编程语言编写一个不错的markdown解析器。
Markdown无法携带数据。无法使用markdown将属性注入文本。好的文档都是关于语义标记的。“定义”不仅是不同的格式或类似格式。这意味着您的文档中实际上存在一个“定义”的概念，作为一个离散的概念。如果需要，您应该能够隐藏所有定义，或者仅显示定义。您应该能够将几个代码示例标记为以不同的语言执行相同的操作。您应该能够生成带有和不带有“ TODO”部分的文档，以便可以在内部和外部共享单独的版本。如果您需要做的只是格式化信息，则无法执行此操作。
Markdown的大多数文档系统都接受这一点。他们通常会添加自己的额外风味，以实现更复杂的内容标记。这导致我们不是在Markdown中编写东西，而是在Markdown方言中保持一致的规则。
在Markdown中，您可以使用三种格式：粗体，斜体和code。如果您想将文档中的某些内容涂成蓝色怎么办？你不能！人们尝试使用Markdown的“扩展”解决此问题。大多数现代处理器都支持表。但是这些扩展是直接添加到Markdown引擎中的，而不是Markdown的“可扩展性”功能的一部分。如果您想拥有新事物，则必须修改引擎的代码。例如，带有标题的图像。这不是Markdown规范的一部分！
Markdown是一种严格的本地格式设置。Markdown如此简单的原因之一是，您可以一次性分析它。但这也意味着您不能整体引用文档。Markdown没有自然的方法在一个页面中提供引用，并自动在另一页面中链接交叉引用。最好的办法是在Markdown链接中对网址路径进行硬编码。您也无法执行“将所有定义收集到词汇表页面中”或“使两个标注框别名相同的文本”之类的操作。
Markdown可以很好地生成HTML，而制作PDF则很糟糕。
我在Markdown中写了Learntla和Practical TLA +。不要犯我的错误。不要在Markdown中编写文档。