Asciidoc简介

Markdown 是现在最流行的轻量级标记语言，Github、Stack Overflow、Smashing Magazine 等网站都使用 Markdown。Markdown 格式简单，纯文本具有很好的可读性。但它对复杂格式（例如表格、图片标题）支持不够，也没有预留扩展语法，不同网站各自扩展产生了很多方言。

社区有不少人意识到问题，其中就有 Jeff Atwood 牵头，联合 Stack Overflow、Github、reddit 的一些员工发起了 Standard Markdown 项目，希望将 Markdown 标准化。没想到项目起步遇到的最大阻力是 Markdown 的创建者 John Gruber，John 很不满意 Jeff 在未充分沟通的情况下宣称自己的项目是“Standard”，经过一番争吵，Jeff 把项目改名为 Common Markdown ，John 也没有加入项目。

这场争吵让我不太看好 Markdown 的前景，没有创建者的支持，Common Markdown 可能又成为一个方言，Markdown 的混乱状况还要继续下去。

最近我在摸索制作电子书制作方案，需要一种更严谨、功能更丰富的标记语言，便开始寻找比 Markdown 更好的选择。现行的轻量级标记语言并不少， Wikipedia 上列出了 17 种（有三种是 Markdown 方言）。经过一些研究之后，我比较看好 AsciiDoc，它的设计初衷就是为了解决写书规模的问题，并且是 O’Reilly 的在线出版平台 Atlas 的推荐语言。经过一番学习，我觉得 Asciidoc 确实很适合电子书制作。

第一印象

AsciiDoc 基本语法跟 Markdown 类似，例如以 = 号开头作为标题、以 * 号开头作为列表项、以空行分割段落等，下面是一段 AsciiDoc 文本：

= Hello, AsciiDoc!
Doc Writer doc@example.com

An introduction to http://asciidoc.org[AsciiDoc].

== First Section

item 1
item 2

[source,ruby]
puts “Hello, World!”
如果学会了 Markdown，再学 AsciiDoc 应该不难。详细的语法说明可以看这份文档： http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ 。

内置更多特性

AsciiDoc 相比 Markdown 支持更多的格式，包括而不限于：

文档属性，设置作者、版本信息等。
语法高亮。
表格。
Include 功能，将大文档拆分几个文件。
自定义块语法，可扩展性。
Markdown 通过自行扩展语法或者使用 HTML 可以实现这些格式，但前者造成文档不通用的问题，后者则直接把展示结构硬编码到了文档中，将来修改会很麻烦。

当然，更多的特性带来更多的学习成本，对于博客等简单文档，这些特性并不是必须的，但对于电子书等大型文档，标准内提供丰富的特性就很有必要，否则就需要自己实现不成熟、不兼容的扩展。

AsciiDoctor

AsciiDoctor 是 AsciiDoc 的 Ruby 实现，也是一个工具链，实现了 AsciiDoc 对 HTML5/DocBook/EPUB/PDF/MOBI 的转换（有的需要借助第三方工具例如 Kindlegen）。相比原版 Python 实现，AsciiDoctor 作了以下改进：

添加模板引擎，可以用 Ruby 的模板语言（例如 erb）自定义输出格式。
处理过程分成解析和生成两步，在解析之后文档转化为 Ruby 对象，可供编程处理。
性能和安全性提升。
通过 JRuby 提供 Java 版本；通过转编译提供 JavaScript 版本。
AsciiDoctor 是一个很宏伟的项目，还有很多子项目在开发中，例如我比较关注的 Asciidoctor PDF 和 Asciidoctor EPUB3，这两个项目用于去掉现有工具链中对 DocBook 的依赖，由原文档直译目标文档。工具链层次的减少可以增加定制便利性，也更方便用户安装。

因为有 AsciiDoctor 这样设计精良的实现，我才决定把精力放到 AsciiDoc 上。

编辑器

轻量级标记语言不依赖编辑器，但好的编辑器会让写作过程更愉快。现在 AsciiDoc 的专用编辑器还不多，我推荐的编辑器是 Atom ，并且加装以下插件：

zen，全屏居中的写作布局。
language-asciidoc，语法高亮。
asciidoc-preview，实时预览。

配色之类可以根据个人喜好配置，Atom 是一个可塑性很强的编辑器。

为什么不用……

我可以估计到有人会向我发问，为什么不用某某标记语言？这里简要回答一下：

LaTex：语法太复杂，导致写作没有乐趣可言。LaTex 适合用于数学公式这类专门场合。
Org mode：基本上是 Emacs 用户在用。
reStructuredText：基本上是 Python 开发者在用。
其他类似。
综合功能、易用性、社区氛围、配套工具来看，目前我觉得 AsciiDoc 最好。

总结

AsciiDoc 是一个成熟的、为大型文档设计的标记语言。如果你在搭建复杂的文档环境，并且认为 Markdown 已经不能满足需求，那么可以试试 AsciiDoc。

Asciidoc简介相关推荐

AsciiDoc 的相关整理
Asciidoc Book Editor based on JavaFX 8 Asciidoc FX is a book / document editor to build PDF, Epub, M ...
AsciiDoc 相关资源
实践的.技术写作的未来乱谈AsciiDoc的书籍编写快速文本处理和发布工具链 Asciidoctor AsciiDoc 简介 asciidoc.org asciidoctor.org AsciiD ...
使用Swagger2Markup实现API文档的静态部署（一）：AsciiDoc
在阅读本文之前,您先需要了解Swagger的使用,如果您还不知道它是用来干嘛的,请先阅读<Spring Boot中使用Swagger2构建强大的RESTful API文档>一文. 前言在 ...
assicdoc 转换html,使用asciidoc生成spring官网风格的文档
spring官方文档看了多少年, 不知道人家是怎么写出来的, 前一段时间折腾 undertow 这个小容器, 又看到了跟spring文档一样风格的文档, 好奇心作祟, 然后就折腾了一下不折腾不要紧, ...
i.MX6 Yocto工程简介与分析
i.MX6Yocto工程简介与分析按照NXP官方网站的说法,i.MX6的源码都发布在Yocto Project Freescale i.MX6 release工程里了.The FSL Yocto P ...
etcd 笔记（01）— etcd 简介、特点、应用场景、常用术语、分布式 CAP 理论、分布式原理
1. etcd 简介 etcd 官网定义: A highly-available key value store for shared configuration and service discov ...
Docker学习(一)-----Docker简介与安装
一.Docker介绍 1.1什么是docker Docker是一个开源的应用容器引擎,基于Go语言并遵从Apache2.0协议开源 Docker可以让开发者打包他们的应用以及依赖包到一个轻量级,可移植 ...
【Spring】框架简介
[Spring]框架简介 Spring是什么 Spring是分层的Java SE/EE应用full-stack轻量级开源框架,以IOC(Inverse Of Control:反转控制)和AOP(Asp ...
TensorRT简介
TensorRT 介绍引用:https://arleyzhang.github.io/articles/7f4b25ce/ 1 简介 TensorRT是一个高性能的深度学习推理(Inference) ...