如何将 UML 图集成到 GitLab 或 GitHub

Question

我想发布我在 public 可用存储库中的一些编程文档。该文档包含格式化文本、一些 UML 图和大量代码示例。我认为 GitHub 或 GitLab 是发布此内容的好地方。

要发布 UML 图，我希望有一些简单的方法可以将它们更新到存储库中并在 wiki 中以图像形式显示。我不想把图表保存在我的电脑里（或云端），每次编辑它们，生成图像，然后发布。

有没有办法将图表放在存储库中（最好使用 PlantUML 语法），link 将它们放在 markdown 文本中，并在每次图表更新时自动更新图像？

Answer 1

上使用 plantuml-gist 可以做到这一点

只需在存储库中放入一个有效的 puml 文件，并在文档中包含一个 link 到此站点。

例如，对于文件 https://github.com/linux-china/plantuml-gist/blob/master/src/main/uml/plantuml_gist.puml in GitHub, you would use http://uml.mvnsearch.org/github/linux-china/plantuml-gist/blob/master/src/main/uml/plantuml_gist.puml 作为您的 link。

这是在 Whosebug 中 link编辑的样子：

UML image http://uml.mvnsearch.org/github/linux-china/plantuml-gist/blob/master/src/main/uml/plantuml_gist.puml

不幸的是，它似乎不适用于 GitLab。我总是得到 "No PUML file found"，即使我已经多次检查路径。

编辑：uml.mvnsearch.org 的服务器似乎已关闭。

Answer 2

编辑：替代代理服务

这种方式与下面的答案有很大的不同并且更简单；它使用 PlantUML proxy service:

http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.github.com/plantuml/plantuml-server/master/src/main/webapp/resource/test2diagrams.txt

GitHub 降价为：

![alternative text](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.github.com/plantuml/plantuml-server/master/src/main/webapp/resource/test2diagrams.txt)

~~此方法无法指定 SVG 格式（默认为 PNG）~~，~~可能无法 work-around评论中提到的缓存bug~~.

尝试后，我发现服务速度很慢，而且似乎没有达到最新版本的 PlantUML。

我发现了一种不那么简单的不同方法，但它可以通过 PlantUML.com 的服务器（在云端）工作。因此，它应该任何可以盗链接到图像的地方。

它利用了 the !includeurl function，本质上是一种间接寻址。 markdown 文件链接到包含图表源的 PlantUML 源。此方法允许修改 GitHub 中的源，并且 GitHub markdown 文件中的任何图像将自动更新。但是创建间接的 URL 需要一个棘手的步骤。

将 URL 获取到原始 PlantUML 源代码，例如 https://raw.githubusercontent.com/linux-china/plantuml-gist/master/src/main/uml/plantuml_gist.puml（使用 joanq 的回答中的示例）
转到http://plantuml.com/plantuml/form（或PlantText.com）并创建一个使用!includeurl URL-TO-RAW-PLANTUML-SOURCE-ON-GITHUB 操作的one-line PlantUML 源代码。继续示例 URL，PlantUML（元）源是：
```
!includeurl https://raw.githubusercontent.com/linux-china/plantuml-gist/master/src/main/uml/plantuml_gist.puml
```
从 PlantUML.com 的图像复制图像 URL，例如 http://plantuml.com:80/plantuml/png/FSfB2e0m303Hg-W1RFPUHceiDf36aWzwVEl6tOEPcGGvZXBAKtNljW9eljD9NcCFAugNU15FU3LWadWMh2GPEcVnQBoSP0ujcnS5KnmaWH7-O_kEr8TU 并将其粘贴到您的 GitHub markdown 文件中。这个URL不会变。
```
![PlantUML model](http://plantuml.com:80/plantuml/png/3SNB4K8n2030LhI0XBlTy0YQpF394D2nUztBtfUHrE0AkStCVHu0WP_-MZdhgiD1RicMdLpXMJCK3TC3o2iEDwHSxvNVjWNDE43nv3zt731SSLbJ7onzbyeF)
```

Bonus：您甚至可以通过将 URL 的 plantuml/png/ 部分修改为 plantuml/svg/ 来访问 SVG 格式关注

![PlantUML model](http://plantuml.com:80/plantuml/svg/3SNB4K8n2030LhI0XBlTy0YQpF394D2nUztBtfUHrE0AkStCVHu0WP_-MZdhgiD1RicMdLpXMJCK3TC3o2iEDwHSxvNVjWNDE43nv3zt731SSLbJ7onzbyeF)

GitHub

上的示例

https://github.com/fuhrmanator/course-activity-planner/blob/master/ooad/overview.md

注意私人回购

正如 davidbak 在评论中指出的那样，私有仓库中的原始文件将有一个 URL 和 token=<LONGSTRINGHERE> ，并且这个标记随着源文件的更新而改变.不幸的是，发生这种情况时降价中断，因此您必须在将文件提交到 GitHub 之后更新自述文件 ，这不是一个很好的解决方案。

Answer 3

这是一个老问题，但在搜索此问题的解决方案时很早就出现了。

更新

GitLab 现在在其 public 产品中同时支持 Mermaid 和 PlantUML 图。开箱即用支持美人鱼。

```mermaid
sequenceDiagram
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob:Another authentication Response
Bob --> Alice: Another authentication Response
```

Example

原答案

其他答案讨论 GitHub，但值得注意的是，如果您在内部部署，GitLab 对此有本地集成。出于某种原因，他们从未在 public 产品中激活该功能。有 tickets open 个可以激活该功能。

如果您使用的是内部托管解决方案，administration documentation

中提供了说明

基本上是你

建立自己的 plantuml 服务器
检查 GitLab 服务器配置中的 Enable PlantUml
在你的 markdown 中写入 PlantUml

```plantuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
   
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
```

Answer 4

GitLab

如其他帖子中所述，已经原生支持 PlantUML。

GitHub

我希望他们也原生支持它，但他们现在不支持。

解决方法

我构建了自己的解决方法，类似于上面提到的 PlantUML 代理，但更好一点。

TLDR:

示例：https://puml-demo.herokuapp.com/github/ghe/lyang/puml-demo/blob/master/README.md
源代码：https://github.com/lyang/puml

长:

支持任意url
它支持 public 和 https://github.com
支持GitHub个企业实例
它不会像 PlantUML 代理解决方案那样将 API 令牌公开为 URL 的一部分
它可以在 GitHub 之外使用，例如在电子邮件、维基、演示文稿等中
私有存储库和 GHE 实例需要您自己的 puml 应用程序并配置了 API 令牌。
示例可以在 https://github.com/lyang/puml

Answer 5

分享我为您处理所有这些的开源项目https://github.com/danielyaa5/puml-for-markdown

工作原理

使用 PlantUML Web 服务呈现 PUML 图

您可以使用在线网络服务使用 PlantUML 来生成图像 on-the-fly。 http://www.plantuml.com/plantuml. You can pass the encoded text of your diagrams to the web service in the url path and it will generate an SVG or PNG for you. Here's a simple HelloWorld example http://www.plantuml.com/plantuml/uml/Aov9B2hXil98pSd9LoZFByf9iUOgBial0000 提供在线演示。大图表会有很长的编码字符串，它们可以超过最大 url 长度。它们在降价文件中看起来也不太好。默认情况下，CLI 将使用 tinyurl.com 服务将 link 缩短为图表。

为 Web 服务编码 PUML 图

CLI 将使用 plantuml-encoder 包来编码 puml 文件。为了支持 hyperlinking 图，我们需要解析 puml 文件中的所有 hyperlink。为文件创建依赖图并执行 DFS，我们首先为叶节点创建 links，然后用 links 替换父节点中的 links 以叶节点。实际上并没有修改puml文件，只是修改了内存中的puml文件内容。默认情况下，tinyurl 免费服务用于缩短 links.

为了支持 !include，我们解析 puml 文件并将任何 !include 替换为引用文件的内容。

解析 Markdown

然后解析 markdown 文件以获取 markdown 注释。如果评论引用了 PlantUML 文件，则将在评论旁边添加 Web 服务 url 的 link。因为这些 link 包含完整的 PlantUML 图编码，所以在私有存储库中使用它们没有问题。

Answer 6

由于 GitLab 支持开箱即用地渲染 PlantUML，您可以使用以下内容：

README.md

This is some example text in a Markdown file. Followed by a PlantUML diagram, loaded from an URL.

```plantuml
!include https://gitlab.com/my-drawing.puml
```

当您 'preview' 文件时，它将呈现文本以及 PlantUML 图的图像。

有关 PlantUMLs !include 指令的详细信息，请参阅 https://plantuml.com/preprocessing#393335a6fd28a804

如何将 UML 图集成到 GitLab 或 GitHub

How to integrate UML diagrams into GitLab or GitHub

git

github

uml

markdown