如何將 UML 圖集成到 GitLab 或 GitHub

Question

我想發布一些我在公共可用存儲庫中的編程文檔。 該文檔包含格式化文本、一些 UML 圖和大量代碼示例。 我認為 GitHub 或 GitLab 是發布此內容的好地方。

為了發布 UML 圖，我希望有一些簡單的方法來將它們更新到存儲庫中並在 wiki 中作為圖像可見。 我不想將圖表保存在我的計算機中（或雲上），編輯它們，生成圖像，然后每次都發布它。

有沒有辦法將圖表放入存儲庫（最好使用 PlantUML 語法），將它們鏈接到 markdown 文本中，並在每次圖表更新時自動更新圖像？

Answer 1

編輯：替代代理服務

這種方式與下面的答案明顯不同且更簡單； 它使用PlantUML 代理服務：

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） ， 和可能無法解決評論中提到的緩存錯誤 .

---

在嘗試了其他答案后，我發現該服務很慢，而且似乎沒有達到 PlantUML 的最新版本。

我發現了一種不太簡單的不同方式，但它通過 PlantUML.com 的服務器（在雲中）工作。 因此，它應該可以在任何可以熱鏈接到圖像的地方工作。

它利用了!includeurl函數並且本質上是一個間接的。 Markdown 文件鏈接到包含圖表源的 PlantUML 源。 此方法允許修改 GitHub 中的源，並且 GitHub Markdown 文件中的任何圖像都會自動更新。 但是它需要一個棘手的步驟來創建指向間接的 URL。

1. 獲取原始 PlantUML 源的 URL，例如， https://raw.githubusercontent.com/linux-china/plantuml-gist/master/src/main/uml/plantuml_gist.puml ://raw.githubusercontent.com/linux-china/plantuml-gist/master/src/main/uml/plantuml_gist.puml（使用 joanq 答案中的示例）

2. 轉到http://plantuml.com/plantuml/form （或 PlantText.com）並創建一個使用!includeurl URL-TO-RAW-PLANTUML-SOURCE-ON-GITHUB操作!includeurl URL-TO-RAW-PLANTUML-SOURCE-ON-GITHUB 。 繼續示例 URL，PlantUML（元）源是：

    !includeurl https://raw.githubusercontent.com/linux-china/plantuml-gist/master/src/main/uml/plantuml_gist.puml

3. 從 PlantUML.com 的圖片中復制圖片 URL，例如， http ://plantuml.com:80/plantuml/png/FSfB2e0m303Hg-W1RFPUHceiDf36aWzwVEl6tOEPcGGvZXBAKtNljW9eljD9NcCFAugNU15FUQCN5GW9eljD9NcCFAugNu15FUQcnSPOdKuVu15FUQcnSPEadwmGithub.com 將您的文件粘貼到文件中這個網址不會改變。

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

獎勵：您甚至可以通過將 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在評論中指出的那樣，私有存儲庫中的原始文件將包含一個帶有token=<LONGSTRINGHERE>的 URL，並且該標記會隨着源文件的更新而變化。 不幸的是，降價會在發生這種情況時中斷，因此您必須在將文件提交到 GitHub后更新自述文件，這不是一個很好的解決方案。

Answer 2

這是一個古老的問題，但它在尋找此問題的解決方案的早期就出現了。

更新

GitLab 現在在其公開發行中同時支持Mermaid和 PlantUML 圖。 美人魚開箱即用。

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

例子

原答案

其他答案討論了 GitHub，但值得注意的是，如果您在內部部署，GitLab 對此具有本機集成。 出於某種原因，他們從未在公開募股中激活該功能。 有門票打開以激活該功能。

如果您使用的是內部托管解決方案，則管理文檔中提供了說明

基本上你

1. 建立你自己的 Plantuml 服務器
2. 檢查在 GitLab 服務器配置中Enable PlantUml
3. 在 Markdown 中寫入 PlantUml

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

Answer 3

我發現可以使用http://uml.mvnsearch.org/上的 plantuml-gist 來做到這一點

只需在存儲庫中放置一個有效的 puml 文件，並在文檔中包含指向該站點的鏈接。

例如，對於 GitHub 中的文件https://github.com/linux-china/plantuml-gist/blob/master/src/main/uml/plantuml_gist.puml ，您將使用http://uml.mvnsearch.org /github/linux-china/plantuml-gist/blob/master/src/main/uml/plantuml_gist.puml作為您的鏈接。

這是在 StackOverflow 中鏈接的樣子：

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

不幸的是，它似乎不適用於 GitLab。 我總是收到“找不到 PUML 文件”的消息，即使我已經多次檢查了路徑。

編輯： uml.mvnsearch.org 上的服務器似乎已關閉。

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

長：

• 它支持任意網址
• 它支持https://github.com上的公共和私有存儲庫
• 它支持 GitHub Enterprise 實例
• 它不像 PlantUML 代理解決方案那樣將 API 令牌作為 URL 的一部分公開
• 它可以在 GitHub 之外使用，例如在電子郵件、維基、演示文稿等中。
• 私有存儲庫和 GHE 實例需要您自己的配置了 API 令牌的puml應用程序。
• 示例可以在https://github.com/lyang/puml 中找到

Answer 5

分享我為你處理所有這些的開源項目https://github.com/danielyaa5/puml-for-markdown

這個怎么運作

使用 PlantUML Web 服務渲染 PUML 圖

您可以通過在線 web 服務使用 PlantUML 即時生成圖像。 http://www.plantuml.com/plantuml上提供了在線演示。 您可以將圖表的編碼文本傳遞給 url 路徑中的 web 服務，它將為您生成 SVG 或 PNG。 這是一個簡單的 HelloWorld 示例http://www.plantuml.com/plantuml/uml/Aov9B2hXil98pSd9LoZFByf9iUOgBial0000 。 大圖會有很長的編碼字符串，它們可以超過最大 url 長度。 它們在 markdown 文件中看起來也不是很好。 默認情況下，CLI 將使用 tinyurl.com 服務來縮短圖表的鏈接。

為 Web 服務編碼 PUML 圖

CLI 將使用 plantuml-encoder package 對 puml 文件進行編碼。 為了支持超鏈接圖，我們需要解析 puml 文件中的所有超鏈接。 為文件創建依賴關系圖並執行 DFS，我們首先為葉節點創建鏈接，然后將父節點中的鏈接替換為葉節點的鏈接。 puml文件並沒有實際修改，只是修改了memory中的puml文件內容。 默認情況下，tinyurl 免費服務用於縮短鏈接。

為了支持.include，我們解析 puml 文件並將任何 !include 替換為所引用文件的內容。

解析 Markdown

然后解析 markdown 文件以獲取 markdown 注釋。 如果注釋引用 PlantUML 文件，注釋旁邊將添加指向 web 服務 url 的鏈接。 因為這些鏈接中包含完整的 PlantUML 圖編碼，所以在私有存儲庫中使用它們沒有問題。

Answer 6

由於 GitLab 支持開箱即用地渲染 PlantUML，您可以使用以下內容：

自述文件.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
```

當您“預覽”文件時，它會將文本與 PlantUML 圖的圖像一起呈現。

有關 PlantUMLs !include指令的更多信息，請參閱https://plantuml.com/preprocessing#393335a6fd28a804

Answer 7

要發布 UML 圖，我想有一些簡單的方法來將它們更新到存儲庫中並在 wiki 中作為圖像可見

現在（2022 年 8 月）在 GitHub 上應該可以實現這一點

Wiki 現在支持數學和美人魚圖

今年早些時候（2022 年 2 月） ，GitHub 在 Markdown 中增加了對 LaTeX 風格的數學表達式和美人魚圖的支持。

然而，直到現在，GitHub wiki 都缺少這種支持。
您現在可以在 GitHub wiki 中使用這些格式化功能。

有關在 GitHub 中使用數學表達式和 Mermaid 的更多信息，請參閱 GitHub 文檔中的創建圖表和編寫數學表達式。

這些圖表包括ULM圖表。