KrokiをGitLabで使う

GitLabで管理しているドキュメントにはあなたは何を使っていますか?最終成果物を外部に渡したいときにはWordやExcel、PDF、Markdownなどをつかっていると思います。内部であれば直接Gitリポジトリを見てもらえるのでMarkdownで置いておくと便利です。

  • Gitだからバージョン管理・履歴管理ができる
  • GitLab上でブラウザでアクセスすればMarkdownはレンダリングされる

Markdownで置いておくと便利だなと感じるポイントです。ただ、テキストだけであれば問題ないのですがUMLなどの図を入れたいと思うとどうしようかと悩むところです。

図を何で作る?

GitLabのMarkdownレンダリング機能は図もレンダリングしてくれます。SVGもPNGもOKです。図を入れるときに何を使って作るか?というのは重要です。Markdownはただのテキストファイルなので手軽に編集できます。更新が簡単だからこそ最新情報がいじされやすいのです。

では図はどうでしょうか?ドローイングソフトを使う場合、それがインストールされていない環境では更新できないので、色々なマシンを使っている場合、更新が後になりがちです。ソフトが入っていても、図の更新は以外と手間がかかり面倒に感じることも多いです。ちょっとした修正、例えば、スペルが間違っていた。詳細設計段階で少し名前が変わったなど、本質的な変更ではない場合には特に面倒に感じるでしょう。

エンジニア向けの資料にはMarkdownの中に図をテキストベースで書くことができるツールがお勧めです。

GitLabでサポートされているKroki

PlantUMLとMermaidについてはGitLab自身が対応しました。KrokiがなくてもPlantUMLやMermaidを使った作図はできます。詳細は GitLab Flavored Markdown | GitLab Diagrams and flowcharts を参照してください。

GitLabはKrokiに対応しています。Krokiはテキストベースで図を書くことができるツールに対する統合APIを提供します。例えば、GitLabでKrokiを設定すれば、Krokiを通してUMLをMarkdownの中でテキストで書けます。

UMLをテキストで書くツールとしてはPlantUMLが有名です。KrokiはPlantUMLに対応しているので、PlantUMLの構文でMarkdownの中にUMLを書けばGitLabがKrokiを使ってレンダリングしてくれます。

Krokiが対応しているのはPlantUMLだけではないです。多すぎるので直接サイトをご覧ください。

Kroki

Krokiのインストール

Krokiのインストールは自前のオンプレサーバーやクラウドインスタンスにインストールできます。ちょっと試したいという感じであれば、無料サービスもあります。

Dockerで簡単に構築できるのでローカル環境でも試せます。

[1] 公式のドキュメントを参考に docker-compose.yml を作る。私の場合は特に変更するところはありませんでした。

version: "3"
services:
    kroki:
        image: yuzutech/kroki
        depends_on:
            - blockdiag
            - mermaid
            - bpmn
            - excalidraw
        environment:
            - KROKI_BLOCKDIAG_HOST=blockdiag
            - KROKI_MERMAID_HOST=mermaid
            - KROKI_BPMN_HOST=bpmn
            - KROKI_EXCALIDRAW_HOST=excalidraw
        ports:
            - "8000:8000"
    blockdiag:
        image: yuzutech/kroki-blockdiag
        expose:
            - "8001"
    mermaid:
        image: yuzutech/kroki-mermaid
        expose:
            - "8002"
    bpmn:
        image: yuzutech/kroki-bpmn
        expose:
            - "8003"
    excalidraw:
        image: yuzutech/kroki-excalidraw
        expose:
            - "8004"

[2] docker-compose を使ってデーモンとして動かす

% docker-compose up -d

GitLabの設定

Dockerで動かしたKrokiにアクセスするようにGitLabを設定します。

[1] 「管理者エリア」の「設定」から「一般」を選択します。

[2] 「Kroki」の「展開」ボタンをクリックします。

[3] 「Enable Kroki」をオンにします。

[4] 「Kroki URL」にDockerで動かしているKrokiのURLを入力します。ポート番号は docker-compose.yml で指定した 8000 を指定します。

[5] 「Additional diagram formats」は特に理由がなければ一通りオンにします。

[6] 「変更を保存」ボタンをクリックして完了です。

GitLabのKrokiの設定画面

Krokiの設定の下にPlantUMLの個別設定もありますが、KrokiがPlantUMLに対応しているので、PlantUMLサーバーを単体で設定する必要はありません。

動作テスト

次のようなMarkdownのファイルを作成してGitLabのリポジトリに入れてみましょう。

WebIDEのプレビューでもレンダリングされるので、ちょっとしたドキュメントならブラウザで完結できます。

# Krokiのテスト用のMarkdown

Markdownの中に書くときはコードブロックとして書く。

コードブロックの言語指定で使用するチャートのツールを指定する。これを忘れるとただのソースコードとしてレンダリングされる。

## チャートの例

### PlantUML

```plantuml
@startuml
GitLab -> Kroki: Request rendering
Kroki -> PlantUML: Request rendering
PlantUML -> Kroki: Image
Kroki -> GitLab: Image
@enduml
```

### Mermaid

```mermaid
sequenceDiagram
GitLab->>Kroki: Request rendering
Kroki->>Mermaid: Request rendering
Mermaid-->>Kroki: Image
Kroki-->>GitLab: Image
```

GitLabでのKrokiを使ったMarkdownへのUMLの埋め込みレンダリングプレビューの例

投稿者プロフィール

林 晃
林 晃アプリ開発者
アールケー開発代表。Appleプラットフォーム向けのアプリ開発が好きなアプリ開発者。アプリの受託開発、技術書執筆、技術指導・セミナー講師。3DCGコンテンツ作成にも取組中です。

基礎から学ぶARKit


「基礎から学ぶARKit」を執筆しました。本書はARKitを使ったARアプリの開発方法を解説した技術書です。

ARKitを使ってARアプリを作るときの流れや基本的なAPIの使い方などをサンプルアプリを作りながら学べます。

詳細

基礎から学ぶMetal


「基礎から学ぶMetal」を執筆しました。本書はMetalを使ってGPUプログラミングを行うための最初のステップを解説するMetalの解説書です。

私が初めてGPUプログラミングを行ったとき、どこから手をつけて、学んでいけば良いのか分からず呆然としました。もし、あのとき、これを教えてくれればという部分を解説しました。本書で解説している部分はMetalの基礎となる部分で、Metalを使うときに必ず触れることになる部分です。

詳細

関連記事

  1. iPhone / iPadのソフトウェアアップデート

  2. GPGの秘密鍵や公開鍵のバックアップ方法

  3. SSHのクライアント側のセットアップ

  4. MayaからUSD, USDZを書き出す方法

  5. SwiftでのバッファアクセスはwithUnsafeBytesを使う

  6. Swiftでコマンドラインツールを作る(コマンドライン引数と標準入出力…

最近の著書

  1. 基礎から学ぶ SwiftUI

最近の記事