一、为什么要批量转换AsciiDoc文档

平时写技术文档的时候，很多人会选择用AsciiDoc这种纯文本格式，因为它语法简单，还能保留文本的可编辑性，不管是团队协作还是个人写笔记都很方便。但当你有十几甚至上百个AsciiDoc文件需要转换成网页、PDF或者电子书的时候，手动一个个敲命令转换就太麻烦了——不仅要重复操作，还容易因为漏改参数导致输出格式乱掉，最后反而花了更多时间在重复劳动上。批量转换的核心就是把这些重复的操作自动化，让你只需要写一次配置，就能处理所有文档。

1.1 手动转换的痛点

举个例子，假设你有50个关于前端框架的adoc文档，每个都要转成HTML放在公司官网，再转成PDF打印存档。手动操作的话，每个文件都要输入类似asciidoctor test.adoc -o test.html和asciidoctor-pdf test.adoc -o test.pdf的命令，不仅敲命令的时间长，万一有某个文件的路径写错，还要重新改，效率极低。而且如果有新的文档加入，还要手动加命令，没法统一管理。

二、Asciidoctor批量转换的核心思路

要实现批量转换，核心是把Asciidoctor的单个转换命令，封装成可以自动遍历所有文档的脚本。这里我们选的技术栈是Shell + Asciidoctor，为什么选Shell？因为Shell是所有开发者电脑上都有的工具，不需要额外安装复杂的环境，写简单的脚本就能搞定批量文件遍历的操作；Asciidoctor则是目前主流的AsciiDoc转换工具，支持几乎所有你需要的格式，而且功能稳定。

2.1 技术栈的适配性

很多人可能会问，为什么不用Python或者Node.js？其实对于批量转换这种简单场景，Shell脚本更轻量，不用依赖额外的语言环境，只要装了Asciidoctor就行，对不同基础的开发者都友好，就算你只会基础的Shell命令，也能看懂并修改脚本。当然如果有更复杂的需求（比如要结合CI流程），再考虑其他工具，但今天我们先讲最实用的轻量方案。

2.2 多格式转换的基础

Asciidoctor本身默认支持转HTML，只要装对应的插件就能支持PDF、EPUB、DocBook这些格式。比如转PDF需要装asciidoctor-pdf插件，转EPUB需要asciidoctor-epub3，这些都可以用Ruby的包管理器gem来装，步骤很简单，后面示例里会讲。

三、详细自动化配置示例（完整可运行）

这个示例的技术栈是Shell + Asciidoctor，从环境准备到脚本代码，每一步都有注释，你可以直接复制下来用，或者根据自己的需求修改。

3.1 环境准备（先装工具）

首先你需要确保电脑上安装了Ruby，因为Asciidoctor是基于Ruby的。如果是Mac或Linux，一般自带Ruby；Windows的话可以用RubyInstaller。然后安装Asciidoctor和需要的转换插件：

# 安装基础转换工具
gem install asciidoctor
# 安装PDF转换需要的插件（如果不需要转PDF可以跳过）
gem install asciidoctor-pdf
# 安装EPUB转换插件（如果需要）
gem install asciidoctor-epub3

3.2 批量转换脚本代码

下面是完整的Shell脚本，你可以把它保存为batch_adoc_convert.sh，然后给它加执行权限就可以用了。脚本的注释已经写得很清楚，你可以根据自己的文件路径调整：

#!/bin/bash
# -------------------------- 配置区域（你可以修改这里的路径） --------------------------
# AsciiDoc源文件存放的目录，这里用当前目录下的adoc_docs文件夹，改成你自己的路径
SOURCE_ADOC_DIR="./adoc_docs"
# 转换后HTML输出的目录，脚本会自动创建不存在的目录
OUTPUT_HTML_DIR="./output/web_docs"
# 转换后PDF输出的目录，同样自动创建
OUTPUT_PDF_DIR="./output/print_docs"
# -------------------------- 配置区域结束 --------------------------

# 先检查源目录是否存在，如果不存在就报错退出
if [ ! -d "$SOURCE_ADOC_DIR" ]; then
  echo "错误：源文档目录 $SOURCE_ADOC_DIR 不存在，请检查路径！"
  exit 1
fi

# 自动创建输出目录，避免因为文件夹不存在导致转换失败
mkdir -p "$OUTPUT_HTML_DIR" "$OUTPUT_PDF_DIR"

# 遍历源目录下所有后缀为.adoc的文件（包括子目录？这里示例先处理当前目录的，要处理子目录可以改find命令）
echo "开始遍历AsciiDoc文件..."
# 这里的find命令：$SOURCE_ADOC_DIR是源路径，-name "*.adoc"是匹配后缀，不包含子目录的话可以去掉 -type f
for adoc_file in $(find "$SOURCE_ADOC_DIR" -maxdepth 1 -name "*.adoc"); do
  # 获取文件名（不带路径和.adoc后缀，比如 src/adoc/test.adoc → test）
  file_base_name=$(basename "$adoc_file" .adoc)
  
  echo "正在处理文件：$adoc_file"
  
  # 1. 转换为HTML格式
  asciidoctor \
    -o "$OUTPUT_HTML_DIR/${file_base_name}.html" \
    # 可选：给HTML加统一的CSS样式，让所有文档的样式一致，不需要的话可以删掉这一行
    -a stylesheet="./custom.css" \
    "$adoc_file"
  
  # 2. 转换为PDF格式（如果不需要转PDF，把这一段注释掉）
  asciidoctor-pdf \
    -o "$OUTPUT_PDF_DIR/${file_base_name}.pdf" \
    # 可选：给PDF用自定义主题，让样式统一，不需要的话删掉
    -a pdf-theme="./custom-pdf-theme.yml" \
    "$adoc_file"
  
  echo "完成：${file_base_name} 转换完毕"
done

echo "所有文档转换任务执行完成！HTML在 $OUTPUT_HTML_DIR，PDF在 $OUTPUT_PDF_DIR"

3.3 脚本的使用方法

  1. 把你所有的AsciiDoc文件放到刚才配置的SOURCE_ADOC_DIR目录里（比如刚才例子里是./adoc_docs）；
  2. 把上面的脚本保存为batch_adoc_convert.sh，放到和adoc_docs同级的目录；
  3. 给脚本加执行权限：打开终端，进入脚本所在目录，输入chmod +x batch_adoc_convert.sh；
  4. 运行脚本：输入./batch_adoc_convert.sh，等待一会儿就能看到转换好的文件了。

四、应用场景

这个批量转换方案适合很多日常场景，比如：

  1. 团队技术文档管理：公司内部的技术说明、API文档都是AsciiDoc写的，批量转成HTML放到内网文档平台，转成PDF给团队成员下载存档；
  2. 个人书籍/笔记整理：用AsciiDoc写的电子书、学习笔记，批量转成多种格式，适配手机、平板、打印等不同需求；
  3. 开源项目文档：开源项目的README、文档都是用AsciiDoc维护，批量转成网页放在项目官网，或者打包成PDF供贡献者参考；
  4. 培训材料输出：内部培训的课程文档，批量转换后生成不同格式的讲义，给讲师和学员使用。

五、技术优缺点

这个方案的优点和缺点都很明显，需要你根据自己的需求判断是否合适：

5.1 优点

  1. 简单高效：不用复杂的环境，写一个几十行的脚本就能搞定批量转换，对新手友好；
  2. 格式统一：所有转换后的文档用相同的样式，不会出现手动转换的样式混乱；
  3. 灵活可控：脚本可以随便修改，比如要加转EPUB，或者过滤某些文件，只要改几行配置就行；
  4. 轻量依赖：只需要装Asciidoctor，不用搭完整的CI/CD流水线，适合小团队或个人快速使用。

5.2 缺点

  1. 脚本灵活性有限：如果要做更复杂的流程（比如转换前检查文档格式、转换后上传到服务器），Shell脚本的扩展性不如Python或者CI工具；
  2. PDF样式需要调整：默认的PDF样式可能不符合你的需求，需要花时间自定义主题，对于新手来说可能有点麻烦；
  3. 环境依赖：需要在运行的机器上装Ruby和Asciidoctor，如果要在服务器上自动运行，还要确保这些依赖都装上；
  4. 错误处理不足：示例里的脚本没有处理转换失败的情况，如果某个adoc文件语法错误，脚本会直接报错退出，不会继续处理剩下的文件。

六、注意事项

用这个方案的时候，有几个细节要注意，避免踩坑：

  1. 源目录的路径：如果你的AsciiDoc文件有子目录，刚才脚本里的find命令加了-maxdepth 1，意思是只搜索当前目录的文件，要处理子目录的话把-maxdepth 1删掉就行；
  2. 插件安装：转PDF的时候一定要装asciidoctor-pdf，否则执行asciidoctor-pdf命令会报错；
  3. 样式配置：如果要统一所有文档的样式，一定要指定样式文件，否则每个adoc的默认样式可能不一样，导致输出的格式乱；
  4. 权限问题：输出目录要确保脚本有写入权限，比如如果你把输出目录设为系统目录，可能会因为权限不够报错，尽量设为当前用户有权限的目录；
  5. 文档语法错误：转换前要确保所有AsciiDoc文件的语法正确，比如没有漏写格式标记，否则某个文件出错会导致整个脚本中断，所以可以在脚本里加错误判断，比如转换后检查文件是否存在。

七、总结

Asciidoctor批量转换AsciiDoc文档的自动化配置，是一个非常实用的技术方案，适合需要处理多个adoc文件的开发者和团队。通过简单的Shell脚本封装，不需要复杂的工具和配置，就能实现多格式的批量转换，解决手动转换的效率问题和格式一致性问题。虽然它的扩展性不如更复杂的工具，但胜在简单易用，对不同基础的开发者都友好，是日常文档维护的绝佳选择。只要按照上面的示例和注意事项操作，你就能快速搭建属于自己的批量转换流程，节省大量重复劳动的时间。