mdmark

図を描く

HTML の使いどころと、文書に部品の定義を書いてフロー図・シーケンス図・グラフを描く手順

文書に構成図・処理の順番・時刻の流れ・数値の変化を図で入れるときに実行する。

前提

文書を描く
設定の features.diagrams がオン（既定）。オフにする手順は機能をオン・オフする

手順

HTML を使うか決める

図とチャートだけ HTML にする

文章・表・手順・リストは Markdown で書く。 HTML は、図・チャートなど見た目のあるものを描くときだけ使う。フロー図・シーケンス図・グラフ・操作できる部品は、HTML を書かずに部品の定義を書く。部品で描けない見た目だけ HTML で書く。書き方は HTML の書き方。 HTML を文書に描かせる手順と、HTML の中にチャートを置く手順はコードブロックのHTMLを描く。

文書に書いた <script> は動かない。動きは部品が持つ。

部品の定義を書く

印で囲んで `json` のコードブロックを 1 つ置く

<!-- flow -->

```json
{
  "title": "問い合わせの受け取り",
  "scope": "受け取りから分類まで",
  "updated": "2026-10-18",
  "width": 520,
  "height": 160,
  "nodes": [
    { "id": "recv", "kind": "script", "x": 20, "y": 48, "w": 140, "h": 64, "name": "受け取り", "sub": "1 通ずつ読む" },
    {
      "id": "classify", "kind": "dm", "x": 300, "y": 48, "w": 140, "h": 64, "name": "分類", "sub": "返信の種類を選ぶ",
      "io": { "in": "問い合わせの本文", "do": "返信の種類から 1 つ選ぶ", "out": "返信の種類" }
    }
  ],
  "wires": [
    { "id": "w-body", "from": "recv", "to": "classify", "line": "flow", "points": [[160, 80], [300, 80]], "label": "本文", "labelAt": [230, 80], "tip": "件名を除いた本文" }
  ]
}
```

<!-- /flow -->

印は flow（フロー図）・sequence（シーケンス図）・chart（グラフ）・param（操作できる部品）。範囲に置く json のコードブロックは 1 つだけ。範囲のコードブロック以外の Markdown と定義の JSON は、描いた文書に残らない。

題と更新日を書く

どの定義も title（題名）・scope（範囲）・updated（更新日。YYYY-MM-DD）を持つ。図の上に題名・範囲・更新日が出る。凡例は書かない。定義に出る箱の種類・線の種類・系列から作られる。

フロー図を書く

箱を書く

nodes の 1 つが箱 1 つ。

項目	説明
`id`	線の端に指す名前。図の中で重ねない
`kind`	箱の種類。下の表から選ぶ
`x`・`y`・`w`・`h`	箱の左上の位置と大きさ。図の中の px
`name`	箱の名前
`tag`・`sub`	名前の上の札と、名前の下の補足。省ける
`io`	`in`（入力）・`do`（処理）・`out`（出力）。ツールチップに出す。LLM・意思決定モデル・スクリプトなど、入力と出力を説明したい箱に付ける
`hint`	箱の説明の文。ツールチップに出す。`io` と一緒に書くと、入力・処理・出力の後に出る。省ける

`kind`	表すもの
`llm`	LLM
`dm`	意思決定モデル
`script`	スクリプト
`mcp`	MCP
`data`	データ
`external`	外部のシステム

tag・name・sub の `` は、索引か用語集の表にある用語なら、本文の用語と同じ破線の下線とツールチップになる。書き方は索引と用語集を書く。

線を書く

wires の 1 つが線 1 本。

項目	説明
`id`	線の名前。図の中で重ねない
`from`・`to`	端の箱の `id`。矢じりは `to` の側に付く
`line`	線の種類。`flow`（処理の流れ）・`read`（読む）・`write`（書く）・`reply`（返す）・`loop`（戻る）
`points`	線が通る点。縦と横だけの折れ線で、箱の縁から縁へ引く
`label`・`labelAt`	線に書く入力の要約と、その位置。省ける
`tip`	入力の詳細。ツールチップに出す。省ける

横の線が縦の線と交わる点は、mdmark が横の線に飛び越えの弧を入れる。同じ向きで重なる線はずらす。自動配置はしないので、x・y・points は自分で置く。

システムの枠と層を書く

内側のシステムを大きな枠で囲むときは frame（title・x・y・w・h）を書く。枠の内側を上から LLM・処理・データの 3 層に分けるときは lanes（label・kind・y・h）を書く。 kind は llm・mcp・data で、層の箱の色がうっすら背景に敷かれる。外部のシステムの箱は枠の外に置く。決まりは構成図の決まり。

シーケンス図を書く

相手とメッセージを書く

<!-- sequence -->

```json
{
  "title": "問い合わせ 1 通の流れ",
  "scope": "受け取りから分類まで",
  "updated": "2026-10-18",
  "participants": [
    { "id": "mail", "kind": "external", "tag": "外部", "name": "メールサーバー" },
    { "id": "recv", "kind": "script", "name": "受け取り" },
    { "id": "classify", "kind": "dm", "name": "分類" }
  ],
  "steps": [
    { "from": "mail", "to": "recv", "label": "問い合わせのメール", "tip": "件名・本文・送り主のアドレス" },
    { "from": "recv", "to": "classify", "label": "本文" },
    { "from": "classify", "to": "recv", "label": "返信の種類", "reply": true }
  ],
  "loop": { "label": "1 へ戻る（次の問い合わせ）" }
}
```

<!-- /sequence -->

participants は左から右へ並べる順、steps は上から下へ時刻の順。 reply を true にしたメッセージは、破線と開いた矢じりの返す線になる。 loop は最後のメッセージから最初へ戻る繰り返しで、右の帯を通る破線と戻り先のラベルになる。 kind は箱の種類と同じ。

グラフを書く

軸と系列を書く

<!-- chart -->

```json
{
  "title": "返信までの時間",
  "scope": "10 月の第 2 週",
  "updated": "2026-10-18",
  "x": { "label": "曜日", "ticks": ["月", "火", "水", "木", "金"] },
  "y": { "label": "分", "min": 0, "max": 60, "step": 15 },
  "series": [
    { "name": "自動返信", "points": [12, 9, 14, 8, 10] },
    { "name": "担当者", "points": [42, 38, 51, 35, 44] }
  ]
}
```

<!-- /chart -->

系列は 1〜4 つ。 points の数は x.ticks の数と同じにする。系列は色と線の模様と点の形の組で分かれ、色だけで見分けなくてよい。

グラフの種類を選ぶ

type で種類を選ぶ。省くと折れ線（line）になる。

`type`	描くもの	系列の書き方
`line`	折れ線	`x.ticks` と `series`
`bar`	棒。系列を色と塗りの模様の組で分ける	`x.ticks` と `series`
`pie`	円。扇形の外に割合（整数の %）、凡例に項目の名前と値を出す	`series` と `x`・`y` の代わりに `items`（`name`・`value`）を 1〜4 つ。凡例の値の単位は `unit`
`scatter`	散布図。系列を色と点の形の組で分ける	`points` を `[x, y]` の組にする。`x` は数値の軸で `ticks` を書かない

縦の軸の min・max・step は 3 つとも書くか、3 つとも省く。省くと、データの最小と最大を含む 1・2・5×10 のべき乗の刻みで切る。

読む人ができること

図は全体が収まる倍率で開く。右上のボタンと、図にフォーカスしているときのキー +・-・0 で拡大・縮小する。縮小と拡大の間の倍率のボタン（125% の形）か 0 で、開いたときの倍率と位置に戻る。ドラッグ・矢印キー・移動のボタンで動かし、全画面のボタンでモーダルに開く。ホイールは文書のスクロールに使う（Shift を押しながらで横）。文字の上では文字を選べる。

矢印のラベルと、io か hint を持つ箱の右上の印は、ポインターを乗せるかフォーカスするとツールチップが出る。箱は右上の印の上でだけ開き、箱の上では開かない。ポインターの形は変わらない。 Esc で消え、ツールチップの上に乗っても消えない。理解に必須のことはツールチップに入れず、箱と線の要約だけで図が読めるようにする。ツールチップを出したくないときは、設定の features.hints をオフにする（機能をオン・オフする）。

反映

即時。mount と update で描くたびに、文書の定義から図を描き直す。

確認

図が描かれている

[...document.querySelectorAll(".mdmark figure.mdmark-diagram")].map((f) => f.dataset.diagram)

書いた順に flow・sequence・chart が出る。題名・範囲・更新日と凡例が図に付いている。

定義の JSON が出ていない

文書に定義の JSON の文字（"nodes" など）が出ていない。

見た目と操作を確かめる

描いた図を確かめるの手順で、操作を通し、スクリーンショットを撮って見る。

定義を読めないとき

定義の閉じの } を消して描く。その図の場所に題 書き方の警告 の枠が出て、フロー図の部品の定義を JSON として読めません（ で始まる本文に、読めなかった行と足りない記号が書かれる。ほかの図と本文は描かれる。

定義の形が合わないときも、その図だけが警告になる。本文に読めない箇所と直し方が書かれる（箱「分類」の種類 robot は使えません。使える種類は llm・dm・script・mcp・data・external です など）。線の端が無い箱の id を指す・id が重なる・系列の点の数が目盛りの数と合わないのも、形の誤りになる。

元に戻す

印と定義を消す。図を描く機能ごと止めるときは、features.diagrams をオフにする。オフにすると印を取り除き、定義を JSON のコードブロックのまま描く。