Asciidoctor Docker 镜像文档

镜像概述和主要用途

Asciidoctor Docker 镜像是 Asciidoctor 工具链的容器化封装，提供独立、一致的运行环境，用于解析和转换 AsciiDoc 格式文档。该镜像集成了 Asciidoctor 核心工具及常用扩展，支持将 AsciiDoc 源文件转换为 HTML、PDF、EPUB、DocBook 等多种输出格式。用户无需在本地配置依赖环境，通过容器即可快速完成文档处理，适用于本地文档生成、CI/CD 流程集成及团队协作场景。

核心功能和特性

核心工具集成

• Asciidoctor 主程序：支持 AsciiDoc 语法解析及基础格式转换（HTML、DocBook 等）。
• 扩展转换器：包含 asciidoctor-pdf（PDF 输出）、asciidoctor-epub3（EPUB 电子书输出）。
• 图表与可视化支持：集成 asciidoctor-diagram，支持 PlantUML、Mermaid、Graphviz 等图表渲染。
• 增强功能：内置语法高亮（Rouge）、数学公式渲染（AsciiMath/LaTeX）、代码块复制功能等。

特性

• 无依赖部署：容器化封装所有依赖（Ruby 环境、字体、转换器库），无需本地安装。
• 跨平台兼容：支持 Linux/Windows/macOS 系统，适配 x86_64/ARM 架构。
• 版本化管理：提供稳定版本标签（如 v2.0.0），确保文档构建环境一致性。
• 轻量高效：基于 Alpine Linux 构建，镜像体积小，启动速度快。

使用场景和适用范围

文档生成场景

• 技术文档自动化：生成 API 文档、用户手册、架构设计文档。
• 出版内容制作：转换 AsciiDoc 为 PDF 书籍、EPUB 电子书。
• 演示文稿生成：通过 asciidoctor-revealjs 生成幻灯片（需额外加载扩展）。

工程集成场景

• CI/CD 流程：与 Jenkins、GitHub Actions 等集成，实现提交后自动生成并部署文档。
• 开发环境统一：团队内标准化文档工具版本，避免本地环境差异导致的格式问题。

临时处理场景

• 快速格式转换：临时将 AsciiDoc 文件转换为 HTML/PDF，无需安装本地工具链。
• 测试文档渲染：验证 AsciiDoc 语法、图表渲染效果。

详细使用方法和配置说明

前置条件

• 已安装 Docker 引擎（20.10+ 版本推荐）。
• 本地目录包含 AsciiDoc 源文件（如 document.adoc）。

基本使用步骤

1. 拉取镜像

# 拉取最新版本
docker pull asciidoctor/docker-asciidoctor:latest

# 拉取指定版本（推荐生产环境使用）
docker pull asciidoctor/docker-asciidoctor:v2.0.0

2. 基本文档转换（HTML 输出）

将本地 AsciiDoc 文件转换为 HTML，输出至当前目录：

# 挂载当前目录到容器内 /doc 目录，执行转换
docker run --rm -v $(pwd):/doc asciidoctor/docker-asciidoctor \
  asciidoctor -o /doc/output.html /doc/document.adoc

• --rm：容器退出后自动删除。
• -v $(pwd):/doc：将本地当前目录挂载到容器内 /doc 目录（容器工作目录）。
• asciidoctor：容器内执行的命令。
• -o /doc/output.html：指定输出文件路径（映射到本地当前目录）。

3. 生成 PDF 格式文档

使用 asciidoctor-pdf 转换器生成 PDF：

docker run --rm -v $(pwd):/doc asciidoctor/docker-asciidoctor \
  asciidoctor-pdf -o /doc/output.pdf /doc/document.adoc

4. 使用图表扩展（asciidoctor-diagram）

渲染包含 PlantUML 图表的 AsciiDoc 文件：

docker run --rm -v $(pwd):/doc asciidoctor/docker-asciidoctor \
  asciidoctor -r asciidoctor-diagram -o /doc/output.html /doc/diagram-demo.adoc

• -r asciidoctor-diagram：加载图表扩展模块。

5. 批量转换目录内文件

转换 /path/to/docs 目录下所有 .adoc 文件为 HTML，输出至 /path/to/output：

docker run --rm -v /path/to/docs:/doc/source -v /path/to/output:/doc/output asciidoctor/docker-asciidoctor \
  asciidoctor -D /doc/output /doc/source/*.adoc

CI/CD 集成示例（GitHub Actions）

在 GitHub 仓库提交代码后自动生成并推送文档：

# .github/workflows/generate-docs.yml
name: Generate Docs
on: [push]

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Generate HTML docs
        run: |
          docker run --rm -v $(pwd):/doc asciidoctor/docker-asciidoctor \
            asciidoctor -D /doc/_site /doc/docs/*.adoc

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

配置参数说明

命令行参数（Asciidoctor 选项）

权限与用户设置

若容器生成的文件权限异常（如属主为 root），可通过 --user 参数指定本地用户 ID/组 ID：

docker run --rm -u $(id -u):$(id -g) -v $(pwd):/doc asciidoctor/docker-asciidoctor \
  asciidoctor /doc/document.adoc

Docker Compose 配置示例

创建 docker-compose.yml 实现配置复用：

version: '3.8'

services:
  asciidoctor:
    image: asciidoctor/docker-asciidoctor:latest
    volumes:
      - ./docs:/doc/source       # 本地 AsciiDoc 源文件目录
      - ./docs/output:/doc/output # 输出目录（自动创建）
    command: >
      asciidoctor 
        -D /doc/output 
        -r asciidoctor-diagram 
        -a icons=font 
        /doc/source/*.adoc

使用方法：在配置文件目录执行 docker-compose up，自动转换 ./docs 下所有 .adoc 文件至 ./docs/output。

常见问题

Q：生成的 PDF 中文显示乱码？

A：需在 AsciiDoc 文件中指定中文字体，或通过 -a pdf-fontsdir 参数加载本地字体目录：

docker run --rm -v $(pwd):/doc -v /path/to/fonts:/fonts asciidoctor/docker-asciidoctor \
  asciidoctor-pdf -a pdf-fontsdir=/fonts /doc/document.adoc

Q：如何查看镜像支持的扩展列表？

A：通过容器内 gem list 命令查看已安装的 Ruby gems：

docker run --rm asciidoctor/docker-asciidoctor gem list