Docker容器中加载asciidoctor-plantuml失败求助

核心问题 #

你遇到的'asciidoctor-plantuml' could not be loaded错误，本质是asciidoctor-plantuml这个Ruby Gem没有在你使用的asciidoctor/docker-asciidoctor容器内安装，官方默认镜像并不包含这个扩展。

是否需要启动PlantUML Server？ #

生成HTML时是否需要启动PlantUML Server取决于你选择的渲染方式：

• 如果用远程渲染：需要启动PlantUML Server，同时在你的adoc文档中配置服务器地址（比如:plantuml-server-url: http://plantuml-server:8080/），还要确保两个容器在同一Docker网络下能互相访问。
• 如果用本地渲染：不需要启动Server，但需要容器内安装PlantUML的jar包，直接在本地生成图片。

不过当前你需要先解决扩展加载的问题，这一步和Server是否启动无关。

排查与解决步骤 #

1. 验证扩展是否安装
   进入容器后执行以下命令，确认asciidoctor-plantuml是否存在：

   gem list | grep asciidoctor-plantuml
   

   如果没有输出，说明确实未安装。

2. 临时安装扩展（单次有效）
   在容器内直接执行安装命令：

   gem install asciidoctor-plantuml
   

   安装完成后再重新执行你的adoc转换命令：

   asciidoctor -r asciidoctor-plantuml my_doc.adoc
   

3. 自定义镜像（永久解决）
   如果你不想每次启动容器都手动安装，可以自定义Docker镜像：
   创建Dockerfile文件：

   FROM asciidoctor/docker-asciidoctor
   RUN gem install asciidoctor-plantuml
   # 如果需要本地渲染，再添加安装PlantUML的命令
   RUN apk add plantuml
   

   构建镜像：

   docker build -t my-asciidoctor .
   

   之后用这个自定义镜像运行容器即可。

4. 后续渲染配置

   • 若使用远程Server：启动PlantUML Server容器时加入同一网络，比如：

     docker network create asciidoctor-net
     docker run -d --name plantuml-server --network asciidoctor-net plantuml/plantuml-server:jetty
     docker run -it --network asciidoctor-net -v $WHERE_ADOCS:/documents/ my-asciidoctor
     

     并在adoc文件头部添加Server地址配置：

     :plantuml-server-url: http://plantuml-server:8080/
     

   • 若使用本地渲染：确保容器内已安装plantuml（自定义镜像时已添加apk add plantuml），无需额外配置Server。

内容的提问来源于stack exchange，提问作者dboy