mermaidはwebベースで動くシステム図やグラフが描けるツール。github上でもレンダリングされるなど、使い勝手がいい。2024/9月あたりにmermaidでアーキテクチャ図をかけるようになった。まだベータ版のようではあるがアーキテクチャ図をコード管理してみたい
サーバやデータベースなどの図形はデフォルトで使用できるが、AWSの各種サービスのアイコンなどはiconifyにあるアイコンを追加することで利用可能になっている
AWSの構成図を作ろうとしたところ、追加したアイコンがレンダリングされたファイルを保存する方法がキャプチャくらいしかなかったため、mermaid-cliを用いてコマンドから保存できるようにしてみた。ついでにgithub actionsで自動生成するのも試してみたのでその手順をかいておく
リポジトリがこれ
https://github.com/uni-3/mermaid-docs
設定
大本のmermaid-cli自体を改修するには全体から見直すような感じがしたので断念して、簡単に引数を追加して
mermaid.registerIconPacks()
—icons という引数を指定することで、追加したいicon packを取得してレンダリングするようにしてみている
入力
mermaid形式でかかれたファイル
.mmd
.md
.md
.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を考慮して出力できなかったので、プレビュー用として使った