GitLab中Asciidoc README无法渲染PlantUML图如何解决？

检查GitLab实例配置 #

• 确认你的GitLab实例（GitLab.com或自托管版本）已启用PlantUML集成：GitLab.com默认开启；自托管版本需管理员在管理中心 > 设置 > 集成 > PlantUML中启用，并配置PlantUML服务地址（如默认的https://plantuml.gitlab.io/plantuml/）。

修正Markdown代码块格式 #

你之前使用的是AsciiDoc语法，但GitLab README默认解析Markdown，这是核心问题。以下是两种正确的Markdown嵌入方式：

方式1：直接内嵌PlantUML代码 #

用```plantuml代码块包裹完整的PlantUML逻辑：

@startuml
actor User
rectangle "BookHub" {
  User --> (Browse Books)
  User --> (Checkout Book)
}
@enduml

方式2：引用仓库内的.puml文件 #

如果要调用仓库里的Diagrams/BookHubUseCase.puml，使用Markdown图片语法结合GitLab渲染端点：

![BookHub Use Case](https://<你的GitLab实例域名>/<用户名>/<项目名>/-/raw/main/Diagrams/BookHubUseCase.puml?inline=false)

替换<你的GitLab实例域名>、<用户名>、<项目名>为实际信息，main换成你的目标分支名（如master）。

验证基础条件 #

• 确保.puml文件和README处于公开分支（或你有访问权限的分支），私有仓库文件需权限允许渲染服务访问。
• 先在本地用PlantUML编辑器验证.puml文件无语法错误，确保能正常生成图形。

强制刷新缓存 #

GitLab会缓存README内容，修改后按Ctrl+F5强制刷新浏览器，或等待几分钟后再查看渲染效果。

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