请不要使用Markdown编写文档 - buttondown

20-03-25 banq

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中编写文档。

 

    

猜你喜欢