markdown-design-doc-viewer 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 playree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,214 @@
+# Markdown Design Doc Viewer
+
+[![CI](https://github.com/playree/markdown-design-doc-viewer/actions/workflows/ci.yml/badge.svg)](https://github.com/playree/markdown-design-doc-viewer/actions/workflows/ci.yml)
+[![Visual Studio Marketplace Version](https://vsmarketplacebadges.dev/version/playree.markdown-design-doc-viewer.svg)](https://marketplace.visualstudio.com/items?itemName=playree.markdown-design-doc-viewer)
+[![Visual Studio Marketplace Installs](https://vsmarketplacebadges.dev/installs/playree.markdown-design-doc-viewer.svg)](https://marketplace.visualstudio.com/items?itemName=playree.markdown-design-doc-viewer)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[English](README.md) | 日本語
+
+設計書としてのMarkdownをプレビューする拡張機能（Markdown 設計書ビューア）です。主な機能として、**mermaidのシーケンス図やフローチャートと処理概要を横並びにして**表示します。
+図の矢印（フローチャートではノード）と処理概要の見出しが紐付き、相互にハイライト・スクロールできます。
+
+![左にシーケンス図、右に紐付いた処理概要](images/screenshot.ja.png)
+
+## 機能
+
+- **横並び表示**: プレビューの幅が十分にあるとき、左に図（スクロールしても固定）、右に処理概要を表示します（紐付いた項目の間には区切り線が入ります）。幅が狭いときは通常の縦並びになります。
+- **矢印・ノードと見出しの紐付け**: 矢印（フローチャートではノード）にマウスを乗せる・クリックすると対応する処理概要がハイライトされ、見出しをクリックすると図の該当箇所へスクロールします。
+- **エディタとの同期**: エディタのスクロールとカーソルにプレビューが追従します（カーソルが矢印やノードの行にあればそれをハイライト）。プレビューをダブルクリックするとエディタの該当行へ移動します。
+- **標準Markdownのまま**: 紐付けの記法はmermaidのコメントとHTMLコメントだけなので、GitHubや標準のMarkdownプレビューでもそのまま正しく表示されます。
+- **設計書でよく使う記法**: 先頭の YAML front matter はメタ情報（タイトル・版数・ステータスなど）の表として表示し（`type: design_doc` を書くとヘッダとして表示。後述）、コードブロックはシンタックスハイライトします。長い表はスクロールしてもヘッダ行を上端に固定して表示します。GitHub のアラート（`> [!NOTE]`）、タスクリスト（`- [ ]`）、脚注（`[^1]`。参照にマウスを載せると内容をポップアップ表示）も表示します。
+- **幅の調整**: 左右の境界をドラッグして幅を変えられます（ダブルクリックで元に戻ります）。プレビューの幅が広いときは本文を最大 1280px の中央のカラムに収めます。プレビューのタイトルバーのボタンで全幅表示と切り替えられます。
+- **ライト・ダークの切り替え**: プレビューは既定で VS Code の配色テーマに従います。プレビューのタイトルバーのボタンで、ライトとダークのうち今と反対の配色に切り替えられます（エディタはダークのまま設計書だけライトで読む、など）。もう一度押すと VS Code の配色に従う状態に戻ります。選んだ配色は `mdDesignDoc.theme` に保存されます。
+- **目次**: プレビュー右端の短い線にマウスを乗せると目次（h1〜h3）が開き、クリックでその見出しへ移動します。現在位置の線は強調表示されます。
+- **図・画像の拡大**: mermaid の図にマウスを乗せると右上に出るボタンで、図を全画面で表示します。ホイールで拡大縮小、ドラッグで移動、ダブルクリックで全体表示に戻り、Esc で閉じます。紐付いた矢印をクリックすると、図を閉じて処理概要へ移動します。画像もクリックすると同じように全画面で表示します（リンクの中の画像はクリックでリンクを開きます）。
+- **検索**: プレビューにフォーカスがあるときに `Ctrl+F`（macOS では `Cmd+F`）でプレビュー内を検索できます。
+- **HTML エクスポート**: コマンド `Markdown 設計書ビューア: 設計書を HTML にエクスポート`（プレビューの右クリックメニューにもあります）で、設計書を 1 つの HTML ファイルに書き出します。図はライトテーマで描画済みの状態で、ローカルの画像は埋め込まれます（プレビューと同じく、文書のフォルダとワークスペース内の画像だけを埋め込み、それ以外はリンクのままにします）。ブラウザでも横並び表示と矢印・見出しのハイライトが動き、印刷すると縦並びになるので、ブラウザの印刷から PDF にできます。警告と紐付け漏れの印は書き出しません。CI やバッチ処理向けにコマンドラインからも実行できます（[コマンドライン（CI）](#コマンドラインci) を参照）。
+
+![プレビューに表示したタスクリスト、GitHub のアラート、折りたたみ](images/screenshot-markdown.ja.png)
+
+## 使い方
+
+Markdownファイルを開いてエディタのタイトルバーにあるプレビューアイコンをクリックするか、コマンドパレットから次のコマンドを実行します。
+
+- `Markdown 設計書ビューア: 設計書プレビューを横に開く`
+- `Markdown 設計書ビューア: 設計書プレビューを開く`
+
+テキストエディタの代わりに開くこともできます。コマンド **エディターを再度開くアプリケーションの選択...**（タブ右上の「テキスト エディター」と表示されている部分）から **設計書プレビュー** を選んでください。Markdownファイルを常にこのプレビューで開くには、同じリストの「'*.md' の既定値を設定する」を選ぶか、設定に次を追加します。
+
+```json
+"workbench.editorAssociations": { "*.md": "mdDesignDoc.editor", "*.markdown": "mdDesignDoc.editor" }
+```
+
+## 書き方
+
+````markdown
+---
+type: design_doc
+title: ログイン機能 設計書
+version: 1.0
+product: Example
+status: 作成中
+updated: 2026-10-11
+---
+
+# ログイン機能 設計書
+
+## シーケンス
+
+```mermaid
+%% @link-headings
+sequenceDiagram
+    Auth->>DB: ユーザー情報を取得
+    %% @ref トークン発行
+    Auth-->>API: アクセストークンを返却
+```
+
+## 処理概要
+
+### ユーザー情報を取得
+
+ID をキーにユーザーを 1 件取得する。
+
+### トークン発行
+
+有効期限 1 時間の JWT を発行する。
+
+<!-- link-headings:end -->
+````
+
+| 記法 | 意味 |
+|---|---|
+| `%% @link-headings` | 必須。その図（シーケンス図またはフローチャート）を処理概要と紐付け、横並びで表示することを示します。mermaidブロック内のどこに書いても構いません。 |
+| 矢印の文言と見出しが同じ | `Auth->>DB: ユーザー情報を取得` は見出し「ユーザー情報を取得」に自動で紐付きます。 |
+| 番号付きの見出し | `### 3. ユーザー情報を取得` も「ユーザー情報を取得」に紐付きます（完全に一致する見出しがない場合、先頭の `3.`、`3)`、`(3)`、`③`、`1.2.3` などの番号を除いて比較します）。 |
+| `%% @ref 見出し` | **直後の**矢印を指定した見出しに紐付けます（文言が見出しと違う場合に使用）。 |
+| `<!-- link-headings:end -->` | 任意。右カラム（処理概要）の終わりを明示します。省略時は次の `%% @link-headings` 付きの図または文書末尾までが右カラムになります。 |
+| front matter | 任意。`---` の行で囲んだメタ情報を先頭に表で表示します。`type: design_doc` を書くと文書のヘッダとして表示します（[設計書のヘッダ](#設計書のヘッダ)を参照）。 |
+
+- 紐付けの対象になるのは、図より**後ろ**にあり、右カラムの範囲内にある見出しだけです。
+- 前後の空白・連続する空白は無視して比較し、矢印の文言中の `<br/>` は空白として扱います。
+- 横並びにするのは `%% @link-headings` のある図だけです（紐付けが1件もなくても横並びにします）。それ以外の図は通常どおり表示し、その中の `@ref` は警告を表示します。
+- リストや引用の中にある図では `%% @link-headings` は効かず、警告を表示します。
+- `@ref` で指定した見出しが見つからない場合は、プレビュー上部に警告を表示します。警告は × ボタンで一時的に隠せます（警告の内容が変わると再び表示します）。
+- `autonumber` を使うと、紐付いた見出しに矢印の番号を表示します（`### 3. ユーザー情報を取得` のように見出しが同じ番号で始まる場合は表示しません）。`mdDesignDoc.headingNumbers` をオフにすると表示しません。
+- 記述漏れに気付けるよう、見出しに紐付いていない矢印は文言を薄く表示します。また、紐付いた見出しと同じレベルなのに矢印がない見出しには「矢印なし」の印を付けます。紐付けが1件もない図では印を付けません。
+- 同じ警告と紐付け漏れは、開いている Markdown ファイルについて「問題」パネルにも表示します（プレビューを開いていなくても表示します）。`%% @link-headings` があるのに紐付けが1件もない図も、こちらには表示します。
+- エディタでは、`%% @ref ` の後ろで処理概要の見出しを補完します（まだ紐付いていない見出しが先に出ます）。紐付け漏れの診断には、電球（`Ctrl+.`）から次のクイックフィックスを使えます: `@ref` を書いて紐付いていない見出しへ紐付ける、矢印と同じ文言の見出しを処理概要に追加する、見つからない `@ref` を既存の見出しに直す。
+- 警告・印・ツールチップは VS Code の表示言語に合わせて日本語または英語で表示します。
+
+![見出しのない矢印「返金 ID」は薄く表示され、矢印のない見出し「在庫に戻す」には「矢印なし」の印が付く](images/screenshot-link-checks.ja.png)
+
+### フローチャート
+
+フローチャート（`graph` / `flowchart`）も同じように紐付けられます。矢印の代わりに**ノード**が見出しと紐付きます。
+
+````markdown
+```mermaid
+%% @link-headings
+flowchart TD
+    A[注文を検証] --> B{在庫あり?}
+    %% @ref 在庫を確保
+    B -->|はい| C[商品を引き当てる]
+```
+
+## 注文を検証
+
+## 在庫あり?
+
+## 在庫を確保
+````
+
+![左にフローチャート、右に紐付いた処理概要](images/screenshot-flowchart.ja.png)
+
+- ノードはラベルと同じ文言の見出しに紐付きます（`A[注文を検証]` → 「注文を検証」）。ラベルのないノード（`A`）は ID を文言として扱い、見出しがなくても紐付け漏れとして扱いません。エッジのラベルは紐付けの対象外です。
+- `%% @ref 見出し` は、直後の行で定義したノードを紐付けます。その行でラベルを書いた最初のノード、なければその行で初めて登場した最初のノード、それもなければその行の最初のノードです。
+- 横向き（`LR` / `RL`）のフローチャートは幅が広く処理概要と横に並べられないため、常に処理概要を図の下に表示します。紐付けは同じように動きます。
+- 見出しに紐付いていないノードは文言を薄く表示し、ノードのない処理の見出しには「ノードなし」の印を付けます。
+- フローチャートには `autonumber` がないため、見出しに番号は表示しません。
+
+## 設計書のヘッダ
+
+設計書では、YAML front matter に `type: design_doc` を書くことをおすすめします。主なメタ情報を表ではなく文書のヘッダとして表示します。
+
+```markdown
+---
+type: design_doc
+title: 注文確定 設計書
+version: 2.1
+product: Example
+status: レビュー中
+updated: 2026-10-01
+owner: commerce-team
+reviewers:
+  - payments-team
+  - inventory-team
+---
+
+# 注文確定 設計書
+```
+
+![ヘッダにタイトル・版数・プロダクト・ステータス・更新日、その下に開いたその他のメタ情報の表](images/screenshot-header.ja.png)
+
+- ヘッダは枠で囲み、左に `title` を太字で、右に `version`（版数）・`product`（プロダクト）・`status`（ステータス）・`updated`（更新日）を縦線で区切って並べます（この順で、書かれていないものは省きます）。
+- それ以外のキー（この例では `owner` と `reviewers`）は、ヘッダの下の折りたたみ（既定で閉じた状態）に表で表示します。`type` 自体は表示しません。
+
+## AI で設計書を書く
+
+AI アシスタント（Claude Code、GitHub Copilot、Cursor など）にこの形式で設計書を書かせるには、[AI 向けの記法ガイド](docs/ai-authoring-guide.ja.md)（[English](docs/ai-authoring-guide.md)）を渡してください。プロジェクトの指示ファイル（`CLAUDE.md`、`AGENTS.md`、`.github/copilot-instructions.md` など）にコピーするか、AI に読ませます。
+
+ガイドでは、ファイルの診断を確認するよう AI に指示しています。VS Code の診断を読めるエージェント（Copilot のエージェントモードや、VS Code に接続した Claude Code など）は、紐付いていない矢印や見出しを自分で見つけて直せます。
+
+## コマンドライン（CI）
+
+HTML エクスポートはコマンドラインからも実行でき、CI やバッチ処理で VS Code なしに設計書を変換できます。`Export Design Doc as HTML` コマンドと同じ HTML ファイルを書き出します（図はプレビューをヘッドレス Chrome で動かして描画します）。
+
+```sh
+npx markdown-design-doc-viewer export docs -o site     # docs/ 以下の Markdown をすべて site/docs/*.html に
+npx markdown-design-doc-viewer export README.md        # 隣に README.html を
+```
+
+Node.js 22 以降と、Chrome か Chromium が必要です。`--chrome <パス>` か `$CHROME_PATH`、なければ `npx playwright-core install chromium` で入れた Chromium、それもなければシステムにインストールされた Google Chrome（GitHub Actions の Ubuntu ランナーには入っています）を使います。日本語などの CJK の文書には、そのフォント（Debian / Ubuntu では `fonts-noto-cjk`）が必要です。ないと図の文字が四角で描かれます。
+
+| オプション | 説明 |
+|---|---|
+| `-o`, `--out-dir <dir>` | HTML をこのフォルダに、`--root` 以下での文書と同じサブフォルダ構成で書き出す。省略時は各文書の隣に書き出す |
+| `--root <dir>` | `/` で始まる画像パスの基準のフォルダ（VS Code のワークスペースに相当）。この中と文書のフォルダの画像は埋め込み、それ以外はリンクのまま。既定はカレントフォルダ |
+| `--lang <lang>` | 文書に加える文言と紐付けの警告の言語。`en`（既定）か `ja` |
+| `--diagram-look <look>` | `neo`（既定）か `classic`。`mdDesignDoc.diagramLook` と同じ |
+| `--split-min-width <px>` | `mdDesignDoc.splitMinWidth` と同じ。既定は `1000` |
+| `--full-width` | 本文を中央の列に収めない（`mdDesignDoc.limitContentWidth` をオフ） |
+| `--no-heading-numbers`、`--no-front-matter`、`--no-sticky-table-header` | 同じ名前の設定をオフにする |
+| `--chrome <path>` | 図の描画に使う Chrome か Chromium |
+| `--strict` | 紐付けの警告（壊れた `@ref` や置き場所の誤ったマーカーなど、プレビュー上部に出るもの）があれば失敗にする。紐付いていないだけの矢印・見出しでは失敗しない |
+
+フォルダは `*.md` と `*.markdown` を探します（`node_modules` とドットで始まるフォルダは除く）。紐付けの警告は標準エラーに出します（GitHub Actions では注釈になります）。文書を書き出せなかったとき、mermaid が描画できない図があったとき（HTML は書き出します）、`--strict` で紐付けの警告があったときは終了コード 1、コマンドラインの誤りは 2 で終わります。
+
+たとえば、リポジトリの設計書をビルドごとに成果物として公開するには:
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 22
+- run: npx markdown-design-doc-viewer export docs -o site
+- uses: actions/upload-artifact@v4
+  with:
+    name: design-docs
+    path: site
+```
+
+## 設定
+
+| 設定 | 既定値 | 説明 |
+|---|---|---|
+| `mdDesignDoc.splitMinWidth` | `1000` | 横並び表示にする最小のプレビュー幅 (px) |
+| `mdDesignDoc.limitContentWidth` | `true` | プレビューの幅が広いとき、本文を最大 1280px の中央のカラムに収める（横並びの図は全幅のまま）。プレビューのタイトルバーのボタンでも切り替えられ、HTML エクスポートにも適用される |
+| `mdDesignDoc.stickyTableHeader` | `true` | 長い表をスクロールしても、ヘッダ行を上端に固定して表示する（プレビューと HTML エクスポート） |
+| `mdDesignDoc.syncEditor` | `true` | エディタとの同期、ダブルクリックでのジャンプを有効にする |
+| `mdDesignDoc.toc` | `true` | プレビュー右端に目次を表示する |
+| `mdDesignDoc.headingNumbers` | `true` | `autonumber` を使ったとき、紐付いた見出しの先頭に矢印の番号を表示する（プレビューと HTML エクスポート） |
+| `mdDesignDoc.diagramLook` | `neo` | mermaid の図の見た目。`neo`（mermaid の標準。フローチャートのノードに影が付く）または `classic`（影のない平坦な見た目）。図の front matter に `config: look:` を書いた図はその指定に従う |
+| `mdDesignDoc.theme` | `auto` | プレビューの配色。`auto`（VS Code に従う）、`light`、`dark` のいずれか。プレビューのタイトルバーのボタンでも切り替えられる。HTML エクスポートは常にライト |
+| `mdDesignDoc.frontMatter` | `true` | 先頭の YAML front matter をメタ情報の表（`type: design_doc` ではヘッダ）として表示する（オフにすると表示しない） |
+| `mdDesignDoc.diagnostics` | `true` | 開いている Markdown ファイルの紐付けの警告と漏れを「問題」パネルに表示する |

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# Markdown Design Doc Viewer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/playree/markdown-design-doc-viewer/actions/workflows/ci.yml/badge.svg)](https://github.com/playree/markdown-design-doc-viewer/actions/workflows/ci.yml)
+[![Visual Studio Marketplace Version](https://vsmarketplacebadges.dev/version/playree.markdown-design-doc-viewer.svg)](https://marketplace.visualstudio.com/items?itemName=playree.markdown-design-doc-viewer)
+[![Visual Studio Marketplace Installs](https://vsmarketplacebadges.dev/installs/playree.markdown-design-doc-viewer.svg)](https://marketplace.visualstudio.com/items?itemName=playree.markdown-design-doc-viewer)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+English | [日本語](README.ja.md)
+
+A viewer for design documents written in Markdown. Its main feature shows **mermaid sequence diagrams and flowcharts side by side with their step descriptions**.
+Each arrow (or flowchart node) in the diagram is linked to a heading in the description, so you can jump back and forth between them.
+
+![Sequence diagram on the left, linked step descriptions on the right](images/screenshot.png)
+
+## Features
+
+- **Side-by-side layout** — when the preview is wide enough, the diagram stays on the left (sticky) while the descriptions scroll on the right, with a line between linked steps. On narrow panes it falls back to the normal vertical layout.
+- **Arrow / node ⇔ heading links** — hover or click an arrow (or a flowchart node) to highlight its description, or click a heading to find it in the diagram.
+- **Editor sync** — the preview follows the editor's scroll position and cursor (an arrow or node is highlighted when the cursor is on its line). Double-click in the preview to jump to the source line.
+- **Plain Markdown** — the link syntax is made of mermaid comments and HTML comments, so the same file still renders correctly on GitHub and in the built-in Markdown preview.
+- **Design document friendly** — YAML front matter is shown as a table of the document's metadata (title, version, status...), or as a header with `type: design_doc` (see below), code blocks are syntax highlighted, the header row of a long table stays at the top while scrolling, and GitHub alerts (`> [!NOTE]`), task lists (`- [ ]`) and footnotes (`[^1]`, whose note pops up when hovering the reference) are rendered.
+- **Resizable** — drag the boundary between the columns to resize them; double-click it to reset. In a wide preview, the text is kept in a centered column up to 1280px wide; the button in the preview's title bar switches it to the full width and back.
+- **Light / dark theme** — the preview follows VS Code's color theme by default. The button in the preview's title bar switches it to the other of light and dark (for example, to read a document in light while the editor stays dark), and pressing it again makes it follow VS Code again. The choice is saved in `mdDesignDoc.theme`.
+- **Table of contents** — hover the short lines at the right edge of the preview to open a table of contents (h1–h3) and jump to a heading. The highlighted line shows where you are.
+- **Diagram and image zoom** — hover a mermaid diagram and click the button at its top right to show it full screen. Scroll the wheel to zoom, drag to pan, double-click to fit it again and press Esc to close. Clicking a linked arrow closes it and shows the step. Images open the same way when clicked (except images in a link, which open the link).
+- **Find** — press `Ctrl+F` (`Cmd+F` on macOS) in the preview to search it.
+- **HTML export** — `Markdown Design Doc Viewer: Export Design Doc as HTML` (also in the preview's context menu) writes the document to a single HTML file, with the diagrams rendered in the light theme and local images embedded (like the preview, only images in the document's folder and the workspace; others stay links). The side-by-side layout and the arrow ⇔ heading highlighting work in the browser too, and printing lays it out vertically, so you can print it to PDF from the browser. Warnings and missing-link marks are left out. It also runs from the command line for CI and batch conversions (see [Command line (CI)](#command-line-ci)).
+
+![Task lists, GitHub alerts and a collapsible section in the preview](images/screenshot-markdown.png)
+
+## Usage
+
+Open a Markdown file and click the preview icon in the editor title bar, or run one of these commands from the Command Palette:
+
+- `Markdown Design Doc Viewer: Open Design Doc Preview to the Side`
+- `Markdown Design Doc Viewer: Open Design Doc Preview`
+
+It can also be opened in place of the text editor: choose **Design Doc Preview** from **Reopen Editor With...** (the editor picker at the top right of the tab bar). To always open Markdown files with it, pick "Configure default editor for '*.md'" in that list, or add this to your settings:
+
+```json
+"workbench.editorAssociations": { "*.md": "mdDesignDoc.editor", "*.markdown": "mdDesignDoc.editor" }
+```
+
+## Writing linked documents
+
+````markdown
+---
+type: design_doc
+title: Login Feature Design
+version: 1.0
+product: Example
+status: Draft
+updated: 2026-10-11
+---
+
+# Login Feature Design
+
+## Sequence
+
+```mermaid
+%% @link-headings
+sequenceDiagram
+    Auth->>DB: Fetch user
+    %% @ref Issue token
+    Auth-->>API: Return access token
+```
+
+## Steps
+
+### Fetch user
+
+Look up the user by id.
+
+### Issue token
+
+Issue a JWT valid for one hour.
+
+<!-- link-headings:end -->
+````
+
+| Syntax | Meaning |
+|---|---|
+| `%% @link-headings` | Required. Marks the diagram (a sequence diagram or a flowchart) to be linked to and shown side by side with its descriptions. Write it anywhere inside the mermaid block. |
+| Arrow label equals a heading | `Auth->>DB: Fetch user` links to the heading `Fetch user` automatically. |
+| Numbered heading | `### 3. Fetch user` also links to `Fetch user` (`3.`, `3)`, `(3)`, `③`, `1.2.3` and similar prefixes are ignored when no heading matches exactly). |
+| `%% @ref <heading>` | Links the **next** arrow to `<heading>` when its label differs from the heading. |
+| `<!-- link-headings:end -->` | Optional. Ends the description column. Without it, the column extends to the next diagram with `%% @link-headings` or the end of the document. |
+| Front matter | Optional. The metadata between the `---` lines is shown at the top as a table, or as the document's header with `type: design_doc` (see [Design document header](#design-document-header)). |
+
+Rules:
+
+- Only headings **after** the diagram (up to the end of the description column) are linked.
+- Labels and headings are compared after trimming and collapsing whitespace; `<br/>` in a label counts as a space.
+- Only diagrams with `%% @link-headings` are shown side by side (even if no arrow is linked). Other diagrams are rendered normally, and an `@ref` in them is reported as a warning.
+- `%% @link-headings` has no effect on a diagram inside a list or blockquote; this is reported as a warning.
+- An `@ref` whose heading cannot be found is reported as a warning at the top of the preview. The × button hides the warnings temporarily; they are shown again when they change.
+- With `autonumber`, linked headings show the arrow's number, unless the heading already starts with it (`### 3. Fetch user`). Turn `mdDesignDoc.headingNumbers` off to hide them.
+- To help spot missing descriptions, arrows without a linked heading are shown faded, and headings at the same level as the linked ones but without an arrow get a "no arrow" mark. Diagrams with no links at all get no marks.
+- The same warnings and missing links are also reported in the Problems panel for open Markdown files, even when no preview is open. A diagram with `%% @link-headings` but no links at all is reported there too.
+- In the editor, the headings of the overview are completed after `%% @ref ` (those without an arrow first). The missing-link diagnostics come with quick fixes (light bulb, `Ctrl+.`): link the arrow to a heading without an arrow by writing a `@ref`, add a heading with the arrow's text to the overview, or point a broken `@ref` to an existing heading.
+- Warnings, marks and tooltips are shown in English or Japanese, following the VS Code display language.
+
+![The arrow "Refund ID" without a heading is faded, and the heading "Restock items" without an arrow gets a "no arrow" mark](images/screenshot-link-checks.png)
+
+### Flowcharts
+
+Flowcharts (`graph` / `flowchart`) are linked the same way, with their **nodes** in place of arrows:
+
+````markdown
+```mermaid
+%% @link-headings
+flowchart TD
+    A[Validate order] --> B{In stock?}
+    %% @ref Reserve stock
+    B -->|Yes| C[Allocate items]
+```
+
+## Validate order
+
+## In stock?
+
+## Reserve stock
+````
+
+![Flowchart on the left, linked step descriptions on the right](images/screenshot-flowchart.png)
+
+- A node is linked to the heading with the text of its label (`A[Validate order]` → `Validate order`). A node without a label (`A`) uses its id and is not reported as missing a heading. Edge labels are not linked.
+- `%% @ref <heading>` links the node defined on the next line: the first node labeled on it, else the first node appearing there for the first time, else its first node.
+- Horizontal flowcharts (`LR` / `RL`) are too wide to put beside their steps, so the steps are always shown below them. The links work the same.
+- Nodes without a linked heading are shown faded, and step headings without a node get a "no node" mark.
+- Flowcharts have no `autonumber`, so no numbers are shown on the headings.
+
+## Design document header
+
+Writing `type: design_doc` in the YAML front matter of design documents is recommended. The main metadata is then shown as the document's header instead of a table:
+
+```markdown
+---
+type: design_doc
+title: Checkout Design
+version: 2.1
+product: Example
+status: In review
+updated: 2026-10-01
+owner: commerce-team
+reviewers:
+  - payments-team
+  - inventory-team
+---
+
+# Checkout Design
+```
+
+![The title, version, product, status and updated date in the header, and the other metadata in a table opened below it](images/screenshot-header.png)
+
+- The header is a box with `title` in bold on the left, and `version`, `product`, `status` and `updated` on the right (in this order, leaving out those not written), separated by lines.
+- The other entries (`owner` and `reviewers` here) are shown in a table folded below the header (closed by default). `type` itself is not shown.
+
+## Writing with AI
+
+To have an AI assistant (Claude Code, GitHub Copilot, Cursor and so on) write documents in this format, give it the [authoring guide for AI](docs/ai-authoring-guide.md) ([日本語](docs/ai-authoring-guide.ja.md)). Copy it into your project's instructions file (`CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md` and so on), or tell the assistant to read it.
+
+The guide also tells the assistant to read the diagnostics of the file. Agents that can read VS Code diagnostics (for example Copilot agent mode, or Claude Code connected to VS Code) can then find and fix arrows and headings that are not linked.
+
+## Command line (CI)
+
+The HTML export also runs from the command line, to convert documents in CI or in a batch, without VS Code. It writes the same HTML file as the `Export Design Doc as HTML` command, with the diagrams rendered by the preview in headless Chrome.
+
+```sh
+npx markdown-design-doc-viewer export docs -o site     # all the Markdown files under docs/ to site/docs/*.html
+npx markdown-design-doc-viewer export README.md        # README.html next to it
+```
+
+It needs Node.js 22 or later, and Chrome or Chromium: `--chrome <path>` or `$CHROME_PATH`, else a Chromium installed with `npx playwright-core install chromium`, else the Google Chrome installed on the system (GitHub Actions' Ubuntu runners have one). Documents in Japanese or other CJK languages need a font for them (`fonts-noto-cjk` on Debian / Ubuntu), or their diagrams are drawn with boxes.
+
+| Option | Description |
+|---|---|
+| `-o`, `--out-dir <dir>` | Write the HTML files to this folder, in the same subfolders as the documents under `--root`. By default, each one is written next to its document. |
+| `--root <dir>` | Folder that image paths starting with `/` are relative to, like the workspace in VS Code. Images in it or in the document's folder are embedded; others stay links. Default: the current folder. |
+| `--lang <lang>` | Language of the texts added to the document and of the link warnings: `en` (default) or `ja`. |
+| `--diagram-look <look>` | `neo` (default) or `classic`, like `mdDesignDoc.diagramLook`. |
+| `--split-min-width <px>` | Like `mdDesignDoc.splitMinWidth`. Default: `1000`. |
+| `--full-width` | Do not keep the text in a centered column (`mdDesignDoc.limitContentWidth` off). |
+| `--no-heading-numbers`, `--no-front-matter`, `--no-sticky-table-header` | Turn off the setting of the same name. |
+| `--chrome <path>` | Chrome or Chromium to render the diagrams with. |
+| `--strict` | Fail when a document has a link warning (a broken `@ref` or a misplaced marker, as shown at the top of the preview). Arrows and headings that are only not linked do not fail. |
+
+Folders are searched for `*.md` and `*.markdown` files, except in `node_modules` and folders starting with a dot. Link warnings are written to the standard error (as annotations in GitHub Actions). The exit status is 1 when a document could not be exported or has a diagram mermaid cannot render (its HTML is written anyway), or with `--strict` a link warning, and 2 for a wrong command line.
+
+For example, to publish the documents of a repository as an artifact of each build:
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 22
+- run: npx markdown-design-doc-viewer export docs -o site
+- uses: actions/upload-artifact@v4
+  with:
+    name: design-docs
+    path: site
+```
+
+## Settings
+
+| Setting | Default | Description |
+|---|---|---|
+| `mdDesignDoc.splitMinWidth` | `1000` | Minimum preview width (px) for the side-by-side layout. |
+| `mdDesignDoc.limitContentWidth` | `true` | In a wide preview, keep the text in a centered column up to 1280px wide (diagrams beside their steps still use the whole width). Also switched with the button in the preview's title bar, and applied to exported HTML. |
+| `mdDesignDoc.stickyTableHeader` | `true` | Keep the header row of a long table at the top while scrolling through it (preview and exported HTML). |
+| `mdDesignDoc.syncEditor` | `true` | Sync the preview with the editor and enable double-click to jump to the source. |
+| `mdDesignDoc.toc` | `true` | Show the table of contents at the right edge of the preview. |
+| `mdDesignDoc.headingNumbers` | `true` | With `autonumber`, show the arrow's number at the start of its linked heading (preview and exported HTML). |
+| `mdDesignDoc.diagramLook` | `neo` | Look of the mermaid diagrams: `neo` (mermaid's default, with shadows on flowchart nodes) or `classic` (flat, without shadows). A diagram with `config: look:` in its front matter keeps its own. |
+| `mdDesignDoc.theme` | `auto` | Color theme of the preview: `auto` (VS Code's), `light` or `dark`. Also switched with the button in the preview's title bar. Exported HTML is always light. |
+| `mdDesignDoc.frontMatter` | `true` | Show the YAML front matter at the top as a table of metadata, or as a header with `type: design_doc`. When off, it is hidden. |
+| `mdDesignDoc.diagnostics` | `true` | Report link warnings and missing links of open Markdown files in the Problems panel. |

package/ThirdPartyNotices.txt

@@ -0,0 +1,28 @@
+Markdown Design Doc Viewer includes the following third-party material.
+
+================================================================================
+GitHub Octicons (https://github.com/primer/octicons)
+Used for the icons of GitHub alerts (src/markdownExtras.ts).
+================================================================================
+
+MIT License
+
+Copyright (c) 2026 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.