設計書を、図と処理概要を並べて読む
Markdown で書いた設計書のビューアです。mermaid のシーケンス図やフローチャートを処理概要と横並びにし、図の矢印（フローチャートではノード）と見出しを紐付けます。
サンプルは設計書を HTML にエクスポートしたものです。矢印や見出しにマウスを載せて、ハイライトを試せます。
標準の Markdown のまま
紐付けの記法は mermaid のコメントと HTML コメントだけなので、同じファイルが GitHub やほかの Markdown プレビューでもそのまま正しく表示されます。
```mermaid
%% @link-headings
sequenceDiagram
Auth->>DB: ユーザー情報を取得
%% @ref トークン発行
Auth-->>API: アクセストークンを返却
```
### ユーザー情報を取得
ID をキーにユーザーを 1 件取得する。
### トークン発行
有効期限 1 時間の JWT を発行する。-
図に印を付ける
シーケンス図・フローチャート・ER 図・状態遷移図に
%% @link-headingsと書くと、その後ろの見出しと横並びで表示されます。 -
処理概要を見出しで書く
矢印やノードは、同じ文言の見出しと紐付きます。
### 3. ユーザー情報を取得のような番号付きの見出しにも紐付きます。 -
文言が違うときは
@ref%% @ref 見出しで、次の矢印を別の文言の見出しに紐付けます。紐付かないものは警告で知らせます。
設計書のための機能
矢印にマウスを載せる・クリックすると対応する処理概要がハイライトされ、見出しをクリックすると図の該当箇所へスクロールします。処理概要をスクロールしても図は固定されます。
フローチャートも
フローチャートも、矢印の代わりにノードを使って同じように紐付けます。ER 図のエンティティや状態遷移図の状態も同じように紐付くので、テーブルごとの定義や状態ごとの説明を図の横に並べられます。横向き（LR / RL）の図は、見出しを横ではなく下に表示します。
書き漏れが分かる
見出しのない矢印は薄く表示し、矢印のない見出しには印を付けます。VS Code では問題パネルにも表示し、クイックフィックスで直せます。
front matter から設計書のヘッダ
YAML front matter に type: design_doc を書くと、タイトル・版数・製品・ステータス・更新日を設計書のヘッダとして表示します。
設計書でよく使う記法
GitHub のアラート、タスクリスト、脚注、折りたたみ、シンタックスハイライトしたコードブロックを表示します。長い表はヘッダ行を固定します。
項目の表
電文・ファイル・画面の項目の表で、表の直前にコメントを書くと、物理名を項目名の下にまとめ、入れ子の項目をツリーで表示します。子の行を折りたたみ、マウスを乗せた行の親と子をハイライトします。ボタンで一時的にふつうの表に戻して見ることもできます。GitHub などではふつうの表のままです。
画面のワイヤーフレーム
HTML で書いた画面のモックを画像のように設計書に取り込み、data-item でパーツに番号を振ります。動いているアプリの画面をコマンドラインで撮って取り込み、CSS セレクタで番号を振ることもできます。パーツは、同じ番号の項目の表の行や見出しと、図の矢印と同じように紐付きます。GitHub などでは画面の画像を代わりに表示できます。
- エディタとの同期エディタのスクロールとカーソルにプレビューが追従します。ダブルクリックでエディタの該当行へ。
- HTML エクスポート図を描画し画像を埋め込んだ 1 つの HTML に。ブラウザの印刷で PDF にもできます。
- 目次右端にマウスを載せると見出しの一覧が開き、クリックで移動します。
- 図・画像の拡大図を全画面で表示し、ホイールで拡大縮小、ドラッグで移動できます。
- ライト・ダークVS Code の配色に従うほか、ボタン 1 つでプレビューだけ切り替えられます。
- AI で書く記法ガイドと Agent Skill で、AI アシスタントにこの形式の設計書を書かせられます。
- Git の履歴との比較コミットを選ぶと差分をプレビューに表示。変わったブロックに印を付け、変わった語を強調します。差分付きで HTML にもエクスポートできます。
- 設計書一覧ワークスペースの設計書を版数・ステータス付きで一覧し、絞り込みや並べ替えができます。
- 幅の調整図と処理概要の境界をドラッグして幅を変えられます。ダブルクリックで元に戻ります。
- 検索Ctrl+F（macOS では Cmd+F）でプレビュー内を検索できます。
はじめる
MIT ライセンスのオープンソースで、無料で使えます。
デスクトップアプリ
VS Code がなくても、Windows・macOS・Linux で設計書を読めます。ファイルを保存すると表示を更新し、拡張機能と同じように HTML へのエクスポートや Git の履歴との比較もできます。
コマンドライン
CI やバッチ処理で設計書を HTML に変換します。Node.js 22 以降と Chrome が必要です。
npx markdown-design-doc-viewer export docs -o site