今天来跟大家伙儿聊聊我最近折腾 adoc 的那点事儿。也不是啥高深玩意儿，就是我自个儿瞎琢磨的一点记录，分享给大家伙儿瞅瞅。
为啥要折腾 adoc ？
起因也简单，就是平时写点东西，有时候用 Markdown，有时候直接用 Word。Markdown ，写起来是快，但稍微复杂点的排版，比如弄个目录，或者引用个图表，就有点不得劲儿了。Word ，功能是强大，但有时候就想纯粹用文本编辑，不想被那些花里胡哨的按钮干扰。特别是版本控制，Word 文档放 Git 里头，那简直是灾难。
后来有一次，看人家技术文档，排版得特别规整，一打听，说是用 AsciiDoc 写的，后缀名就是 .adoc。我寻思，这玩意儿听着好像比 Markdown 专业点，就想着自己也捣鼓捣鼓。
开始动手，先装家伙事儿
万事开头难，我一开始以为跟 Markdown 差不多，随便找个编辑器就能写。结果上网一查，好家伙，还挺多讲究。要生成好看的 PDF，光有文本还不行，得有专门的工具来转换。
我主要的目标是能把 .adoc 文件转成 PDF。搜了一圈，发现大伙儿都推荐用一个叫 asciidoctor-pdf 的工具。这名字听着就挺对口。
要装这个 asciidoctor-pdf，得先有 Ruby 环境，因为它是用 Ruby 的包管理器 gem 来装的。我电脑上之前好像装过 Ruby，但是版本有点老，gem 命令也不太好使。没办法，只能从头开始折腾 Ruby。
第一步，装 Ruby。 我去 Ruby 官网下了个最新的稳定版，一步步安装，添加到环境变量。这个过程还算顺利，没出啥幺蛾子。
第二步，确保 gem 命令能用。 Ruby 装好后，自带了 gem。我在命令行里敲了敲 gem -v，能出来版本号，心里踏实了一半。
第三步，安装 asciidoctor-pdf。 这才是正主儿。我照着网上的教程，在命令行里敲了：
gem install asciidoctor-pdf --pre
为啥要加个 --pre ？据说是为了用上最新的预发布版，可能修复了一些 bug 或者支持了新特性。咱也不懂，照做就是了。然后就是漫长的等待，看着命令行里一堆东西下载、编译、安装。中间还遇到过一两次网络问题， пришлось重试。折腾了好一阵子，总算是提示安装成功了。不容易！
写第一个 adoc 文件试试水
工具装好了，总得写点东西试试。我就新建了个文本文件，比如叫 my_first_*。
然后我就照着网上找的简单教程，写了几行：
= 我的第一个 AsciiDoc 文档
张三
v1.0, 2023-10-27
这里是文档的摘要，可以写几句概括性的话。
== 第一章：简介这是一个简单的段落。AsciiDoc 的语法感觉比 Markdown 稍微复杂一点，但功能也更强。=== 1.1 小节标题
这是一个无序列表项 这是另一个列表项. 这是一个有序列表项. 第二个有序项
我还试了试加粗：这个是加粗的文字，还有斜体：_这个是斜体的_。
写的时候就感觉，这玩意儿的标记符号跟 Markdown 不太一样。比如一级标题是一个等号开头，二级标题是两个等号。列表啥的也略有不同。不过多写写也就习惯了。
生成 PDF，见证奇迹的时刻！
写完保存。接下来就是最关键的一步了：把它变成 PDF！
我打开命令行，切换到我那个 my_first_* 文件所在的目录，然后信心满满地敲下了命令：
asciidoctor-pdf my_first_*
回车！紧张地等待了几秒钟。命令行没报错，然后在文件夹里，果然出现了一个 my_first_* 文件！
我赶紧双击打开。你还别说，生成的 PDF 文档板式还真挺规整的！标题、作者、日期、章节标题、列表，都自动排好了，字体也挺舒服。比我之前用 Markdown 转 PDF 的效果要好上不少，看起来专业多了。
我还试了试更复杂的，比如插入图片、代码块、表格。发现 AsciiDoc 对这些的支持都挺不错的。特别是代码块高亮，比 Markdown 原生的要好控制。还有文档间的交叉引用、脚注什么的，这些高级功能让写复杂文档变得方便多了。
一点小总结
这回折腾 adoc 的实践，虽然前面安装环境花了不少功夫，但结果还是挺让我满意的。这玩意儿确实是个写技术文档的好帮手。
- 优点：功能强大，排版控制比 Markdown 精细，特别适合生成专业的 PDF 文档和书籍。语法虽然多，但习惯了也还
- 缺点：上手门槛比 Markdown 高一点，主要是环境配置和工具链要熟悉一下。写简单笔记可能不如 Markdown 轻快。
现在我写一些需要正式输出的文档，或者篇幅比较长的技术说明，都开始尝试用 AsciiDoc 来写了。感觉一旦熟悉了它的套路，效率还是挺高的。以后再有什么心得，再来跟大家伙儿分享！
还没有评论，来说两句吧...