使用Asciidoc代替Markdown和Word撰写开发文档

2019独角兽企业重金招聘Python工程师标准>>>

开发文档一般都由Word或Markdown（格式）撰写，前则多见于企业项目，后则在开源界很流行。但在实际使用中总觉得不尽人意。

他们的不是

Word的问题

1. 表现上：格式过于复杂，导致写出来的文档排版、格式很不统一，千人千面，不利于标准化
2. 工具上：要么收费（MS）要么广告多（WPS）要么不稳定（一些开源的Office），另外这些都是很重工具
3. 不被开源界待见，你说你写了个开源工具，文档是word的，很不和谐呀……:confused:

Markdown的问题

1. 表现上：绝对是矫枉过正了，它的语法太简单了，用MD写一篇文章（如本文）还凑合，但要写一个文档的话束缚太多了，谁用谁知道
2. 工具上：Gitbook不错，将MD文档用GIT托管是个很不错的Idea，不过它的新版本把导出功能给阉割了（需要用命令行处理），不厚道，有点被gitbook平台绑架的感觉

说了这两个东西不是，那么自然会引荐更合适的喽，这就是我们主角 Asciidoc :heart:

你的好

Asciidoc有什么魅力呢？

1. 简洁而不简陋的语法，它专门为编写书籍而生，在语法的支持上很到位，但不像Word那样可以随性，可以让你的文档更统一美观
2. AsciidocFX工具开源跨平台，使用体验很不错，更可以导出HTML、PDF、EBook等格式
3. Gitbook也支持这个语法（如果你希望用它的话）

一图胜千言

如何学习Asciidoc？

1. 了解语法 http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
2. 有个中语版的语法介绍 http://houqp.github.io/wbwa/wbwa.html
3. 有更好的示例吗？当然有喽，用AsciidocFX可以方便地建书籍示例：

它生成的HTML如下：

不要怀疑，这些图及公式是Asciidoc语法生成的图片！

Enjoy!

转载于:https://my.oschina.net/gudaoxuri/blog/524132