VitePress で Mermaid が描けるようにする

はじめに

こんにちは、がんがんです。

私は普段 Mermaid + GitHub Issueでシーケンス図を描いています。設計作業が捗り非常に便利で助かっています。
ただ、ドキュメントをどこかにホスティングしたい場合や社内ドキュメントを整備したい場合は環境を考える必要があります。

私はサクッとドキュメント環境を整えられる VitePress を選択することが多く、VitePress上でMermaidが使えないかなと調べてみました。
すると記事には出会えなかったものの、Mermaid Pluginがありました。

そこでVitePress上でMermaid環境を構築してみます。

実験

実験環境

今回は以下のような環境で実験を進めます。

• VitePress: v1.5.0
• pnpm workspace を利用した monorepo 構成
• ディレクトリ構成は最終的に以下の通り

$ tree .
.
├── docs/
│   ├── .vitepress/
│   │   └── config.ts
│   ├── adr/
│   ├── design/
│   ├── index.md
│   └── package.json : docs用
├── src/ : アプリケーション
└── package.json : root用

モノレポ構成で実験を進めていたためこのような構成となっています。アプリケーション近くにdocsを配置するよくある構成かと思います。

step1: VitePress環境を構築する

まずはVitePress環境を構築します。設定は好みで大丈夫です(今回は全てデフォルトで進めています)

terminal

npx vitepress init

設定ファイルは以下のようになっています。

.vitepress/config.ts

import { defineConfig } from 'vitepress';

export default defineConfig({
  title: 'Design Docs',
  description: 'draft',
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      // initで生成されたまま
      { text: 'Examples', link: '/markdown-examples' }
    ],
    sidebar: [
      {
        text: 'Design Docs',
        items: [
          { text: '機能1', link: '/design/feature1' },
          { text: '機能2', link: '/design/feature2' }
        ]
      },
      {
        text: 'Architecture Decision Record',
        items: [
          { text: 'ドキュメント環境構築', link: '/ADR/docs-env' }
        ]
      }
    ],
    socialLinks: [
      {
        icon: 'github',
        link: 'https://github.com/shinGangan'
      }
    ]
  }
});

step2: Mermaidプラグインを追加する

続いて Mermaid Pluginを追加します。

terminal

pnpm add -D vitepress-plugin-mermaid mermaid

設定ファイルは以下のように変更します。

.vitepress/config.ts

- import { defineConfig } from 'vitepress';
+ import { withMermaid } from 'vitepress-plugin-mermaid';

- export default defineConfig({
+ export default withMermaid({
  title: 'Design Docs',
  description: 'draft',
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      // initで生成されたまま
      { text: 'Examples', link: '/markdown-examples' }
    ],
    sidebar: [
      {
        text: 'Design Docs',
        items: [
          { text: '機能1', link: '/design/feature1' },
          { text: '機能2', link: '/design/feature2' }
        ]
      },
      {
        text: 'Architecture Decision Record',
        items: [
          { text: 'ドキュメント環境構築', link: '/ADR/docs-env' }
        ]
      }
    ],
    socialLinks: [
      {
        icon: 'github',
        link: 'https://github.com/shinGangan'
      }
    ]
  },
+ mermaid: { theme: 'forest' },
+ mermaidPlugin: { class: 'mermaid my-class' }
});

実際に表示させる

試しに以下のようなシーケンス図を用意します。

このシーケンス図をfeature1.mdに記載しVitePress上で上手く表示できるのか試します。

terminal

# 単一で実行する場合
pnpm docs:dev

# monorepoの場合
pnpm -C docs docs:dev

実行し以下のような表示が確認できたら成功です。

おわりに

今回はVitePress上でMermaidの描画環境を用意しました。
VitePressは非常に手軽でサクッとドキュメント環境を用意するのに適しています。また、シーケンス図を描きたい時はmarkdown上で描けるMermaidが手軽で便利です。
この2つの手軽で便利を組み合わせることが出来てよかったです。

VitePressにはOpenAPI用のプラグインもあり、本プラグインも合わせて利用することで設計・APIドキュメントを簡単に用意することが可能です。一考の余地がありますね。

https://vitepress-openapi.vercel.app/

ドキュメント環境はトレンドに左右されることが多くほしい情報がなかなか手に入りにくいです。
そのため、小さなメモでも適宜残していけたらと思います。