用Asciidoc来写作
文章目录
Markdown语法过于简单，规范不够标准，经常要花很多时间去适配不同工具，别的语言是熟能生巧，这个语言是越用越怀疑，这对于事事都想精细化控制的我来说是不可接受的。最近通过各种对比和实践，尝试了Asciidoc后，就彻底迷上了，现在日常文档已经基本切换到Asciidoc了，本文则是第一篇Asciidoc格式的文章，自然是贡献给Asciidoc这个主题了。
Markdown与Asciidoc对比
开始之前建议先过目一下 Markdown与Asciidoc的语法对比。
互相转换
由于目前还是在熟悉asciidoc阶段，所以我是根据需要将markdown语法手工转为asciidoc，后面熟练后可以尝试通过工具（asciidoctor和pandoc）转换，转换方法：markdown → docbook → asciidoc 反之亦然。
当然，如果嫌过程麻烦，可以自己写个脚本，毕竟大部分文章格式都非常简单，不会使用太多标记语法，比如我的一些文档就是通过批量替换完成的，替换规则：
-
`# ` → `== `，在文档中asciidoc的"="是整个文章的标题，所以markdown中的标题要降级一级标题
-
#→=，在上一步基础上替换 -
`1. ` → `. `，有序编号替换，以此类推 `2. `、`3. ` ……
-
``→----，代码片段 -
其他常用标记，如url连接，则需要手工修改
文本格式
asciidoc做为标记语言，语法优雅而严谨，比如对于markdown暂不支持的表格，不管是文本格式还是预览格式，都非常直观：
.表格标题
|=============
|表头1 |表头2
|11 |22
|11 |22
|=============引用
- 几种常见的引用语法
-
- include
-
包含外部文件中的内容。语法：
include::xx.adoc[]，可以通过该语法将各个段落或文本片段组织聚合起来，这非常有利于写长篇文字的骨架构思，然后在慢慢的填充各个段落细节，或者是半自动文档，比如程序开发手册，手工写一个指引段落结构，然后引用程序自动生成文本片段。 - image
-
嵌入图片。语法：
image::xx.jpg[] - video
-
嵌入视频。语法：
video::xx.mp4[]
转义
asciidoc在写段落片段时，经常会纠结该用几级标题，我的做法是有内容的段落偏多都只带标题，如果需要层级，则使用有序列表来实现。目前来看确实很灵活，段落片段可以在任何标题层级下引用。当然这里有些语法小缺陷看起来非常难受，就是要要经常用 + 来转义换行符，比如:
-
换行符要在文本结尾处加 ` +`
-
引用代码片段或表格等需要加空行隔离的则要在空行开头加
+
如：
. 步骤1 +
步骤1的说明
.. 部署1.1
+
|===
表格或者代码片段
|===属性
可以通过定义属性，然后在文本中使用属性。
-
定义方法：
:属性名: 属性值。 -
使用方法:
-
文本：
{属性名} -
代码块，在块申明增加subs，如
[source, subs="verbatim,attributes"]，然后在代码块中是{属性名}
-
|
Tip
|
asciidoctor默认生成html是没有icon小图标，需要手工申明： :icons: font
|
关于写作工具
尝试过使用过编辑工具AsciidocFX，可以实时预览，可以到处各种文档，但是对于中文支持不是很好，也不支持半角符号。
所以我现在基本都是用sublime进行写作，结合谷歌浏览器插件”Asciidoctor.js Live Preview“进行预览，非常高效。