uni memo

mermaid-cliをforkしてアーキテクチャ図のsvgを出力させてみた

mermaid-cliをforkしてアーキテクチャ図のsvgを出力させてみた

mermaidはwebベースで動くシステム図やグラフが描けるツール。github上でもレンダリングされるなど、使い勝手がいい。2024/9月あたりにmermaidでアーキテクチャ図をかけるようになった。まだベータ版のようではあるがアーキテクチャ図をコード管理してみたい

サーバやデータベースなどの図形はデフォルトで使用できるが、AWSの各種サービスのアイコンなどはiconifyにあるアイコンを追加することで利用可能になっている

AWSの構成図を作ろうとしたところ、追加したアイコンがレンダリングされたファイルを保存する方法がキャプチャくらいしかなかったため、mermaid-cliを用いてコマンドから保存できるようにしてみた。ついでにgithub actionsで自動生成するのも試してみたのでその手順をかいておく

リポジトリがこれ

https://github.com/uni-3/mermaid-docs

設定

大本のmermaid-cli自体を改修するには全体から見直すような感じがしたので断念して、簡単に引数を追加して

mermaid.registerIconPacks()
を実行するようにした、forkしたリポジトリはこちら

—icons という引数を指定することで、追加したいicon packを取得してレンダリングするようにしてみている

入力

mermaid形式でかかれたファイル

.mmd
としている。
.md
でもいいが、mermaid-cliは
.md
拡張子のとき、複数箇所のmermaidの図をすべて別ファイルとしてで出力する。入力ファイル名と出力ファイル名を1対1で対応させたいので
.mmd
前提にしている

デフォルトではダウンロードされていないlogos、mdiのicon packを使っている

  • ファイル

test.mmd
として作成

architecture-beta
    group api(logos:aws-lambda)[API]

    service db(logos:aws-aurora)[Database] in api
    service disk1(logos:aws-glacier)[Storage] in api
    service disk2(logos:aws-s3)[Storage] in api
    service server(logos:aws-ec2)[Server] in api
    service alert(mdi:alert-octagram)[icon] in api

    db:L -- R:server
    disk1:T -- B:server
    disk2:T -- B:db
  • コマンド
# instal cli
node install github:uni-3/mermaid-cli#add-iconify-support

# generate mmd as svg with iconify
npx mmdc -i ./docs/*.mmd --icons logos mdi

出力

test.svg
として作成される

gihtub actionsでやるとこんな感じauto-commit系のactionsたくさんあったが、どれがいいかはよくわかってない

name: Generate Mermaid Diagrams

on:
  pull_request:
    paths:
      - '**.mmd'

jobs:
  generate-diagrams:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    env:
      ICON_PACKAGES: '["logos", "mdi"]'
    
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
    
    - name: Get changed files
      id: changed-files
      uses: technote-space/get-diff-action@v6
      with:
        PATTERNS: |
          **/*.mmd

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
    
    - name: Install dependencies
      run: npm ci
      if: env.GIT_DIFF_FILTERED
    
    - name: Generate Diagrams
      run: |
        ICONS=$(echo '${{ env.ICON_PACKAGES }}' | jq -r '. | join(" ")' | sed 's/^/--icons /')
        CHANGED_FILES=${{ env.GIT_DIFF_FILTERED }}

        if [ -n "CHANGED_FILES" ]; then
          echo "Generating diagrams for changed files: $CHANGED_FILES"
          for file in $CHANGED_FILES; do
            output_file=$(echo "$file" | sed 's/\.mmd$/.svg/' | sed 's/^docs\//docs\/auto_generated\//')

            echo "Processing $file"
            npx mmdc -i "$file" -o "$output_file" --icons $ICONS --puppeteerConfigFile puppeteer-config.json
          done
        else
          echo "No Mermaid files changed"
          exit 0
        fi
    
    - name: Auto Commit
      uses: stefanzweifel/git-auto-commit-action@v5
      with:
        commit_message: Generate Mermaid diagrams for changed files
        file_pattern: '**/*.svg'
        pull_style: rebase

puppeteer周りでエラーが出たので、リポジトリには以下のpuppeteer-config.jsonを追加している。chatGPTにきいて解決したので内容はよくわかってない

Error: Failed to launch the browser process!
[1222/055557.168688:FATAL:zygote_host_impl_linux.cc(128)] No usable sandbox! If you are running on Ubuntu 23.10+ or another Linux distro that has disabled unprivileged user namespaces with AppArmor, see https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md. Otherwise see https://chromium.googlesource.com/chromium/src/+/main/docs/linux/suid_sandbox_development.md for more information on developing with the (older) SUID sandbox. If you want to live dangerously and need an immediate workaround, you can try using --no-sandbox.

TROUBLESHOOTING: https://pptr.dev/troubleshooting
  • puppeteer-config.json
{
    "args": [
        "--no-sandbox"
    ]
}

ちなみにvscode上でプレビューをみながら編集したいときは Markdown Preview Enhancedのextensionを使う方法もある。icon packの追加もできる(https://shd101wyy.github.io/markdown-preview-enhanced/#/ja-jp/diagrams?id=mermaid)export時にiconifyを考慮して出力できなかったので、プレビュー用として使った

2024, Built with Gatsby. This site uses Google Analytics.