markdown-design-doc-viewer 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.ja.md +18 -5
  2. package/README.md +18 -5
  3. package/ThirdPartyNotices.txt +2654 -0
  4. package/dist/cli.js +72 -59
  5. package/dist/export.css +1 -1
  6. package/dist/export.js +1 -1
  7. package/dist/webview.css +1 -1
  8. package/dist/webview.js +443 -442
  9. package/l10n/bundle.l10n.ja.json +123 -1
  10. package/package.json +21 -2
package/README.ja.md CHANGED
@@ -12,13 +12,14 @@
12
12
 
13
13
  ![左にシーケンス図、右に紐付いた処理概要](https://raw.githubusercontent.com/playree/markdown-design-doc-viewer/main/images/screenshot.ja.png)
14
14
 
15
- **[サンプル](https://playree.github.io/markdown-design-doc-viewer/ja/)**: このコマンドで [examples/screenshot.ja.md](https://github.com/playree/markdown-design-doc-viewer/blob/main/examples/screenshot.ja.md) から書き出した HTML です。
15
+ **[サンプル](https://playree.github.io/markdown-design-doc-viewer/ja/sample/)**: このコマンドで [examples/screenshot.ja.md](https://github.com/playree/markdown-design-doc-viewer/blob/main/examples/screenshot.ja.md) から書き出した HTML です。
16
16
 
17
17
  ## 使い方
18
18
 
19
19
  ```sh
20
20
  npx markdown-design-doc-viewer export docs -o site # docs/ 以下の Markdown をすべて site/docs/*.html に
21
21
  npx markdown-design-doc-viewer export docs -o site --index # 加えて文書の一覧を site/index.html に
22
+ npx markdown-design-doc-viewer export docs -o site --diff-base v1.0 # タグ v1.0 からの差分付きで
22
23
  npx markdown-design-doc-viewer export README.md # 隣に README.html を
23
24
  ```
24
25
 
@@ -47,16 +48,19 @@ md-design-doc export docs -o site
47
48
  | `--no-heading-numbers` | 紐付いた見出しの先頭に矢印の番号（`autonumber`）を表示しない |
48
49
  | `--no-front-matter` | YAML front matter（メタ情報の表、`type: design_doc` ではヘッダ）を表示しない |
49
50
  | `--no-sticky-table-header` | 長い表のヘッダ行をスクロール中に上端に固定しない |
51
+ | `--no-table-tree-highlight` | ツリーとして表示する表（表のオプションの `level=`）で、マウスを乗せた行の親と子をハイライトしない |
50
52
  | `--chrome <path>` | 図の描画に使う Chrome か Chromium |
51
- | `--strict` | 紐付けの警告（壊れた `@ref` や置き場所の誤ったマーカーなど）があれば失敗にする。紐付いていないだけの矢印・見出しでは失敗しない |
52
- | `--index` | 書き出した文書の一覧を `--out-dir`（必須）の `index.html` にも書き出す。フォルダごとの表に、タイトル（リンク）・ファイル名と、front matter の `version`・`product`・`status`・`updated` を載せる |
53
+ | `--strict` | 警告（壊れた `@ref` や置き場所の誤ったマーカーなどの紐付けの警告、適用できない表のオプション）があれば失敗にする。紐付いていないだけの矢印・見出しでは失敗しない |
54
+ | `--diff-base <rev>` | 各文書の、git のリビジョン `<rev>`（タグ・コミット・ブランチ）からの差分を表示する。VS Code 拡張の履歴との比較と同じく、追加・変更・削除したブロックに緑・青・赤の帯を付け、変わった語を強調し、変更した図には変更前の図を折りたたんで添える。ページ下部のバーで前後の変更へ移動したり、差分を隠したり表示したりできる。そのリビジョンの同じパスにない文書（その後に追加・名前を変更したもの）は全体を追加として表示する。git と、クローンにそのリビジョンまでの履歴が必要（[GitHub Actions](#github-actions) を参照）。`--index` と使うと、一覧に各文書の差分の列が付く |
55
+ | `--index` | 書き出した文書の一覧を `--out-dir`（必須）の `index.html` にも書き出す。フォルダごとの表に、タイトル（リンク）・ファイル名と、front matter の `version`・`product`・`status`・`updated` を載せる。ページの検索欄で文書を絞り込め、列見出しで並べ替えられる |
53
56
  | `--index-title <title>` | `index.html` のタイトル。既定は `Design Docs`（`--lang ja` では `設計書一覧`） |
57
+ | `--index-design-docs` | `index.html` に設計書（front matter に `type: design_doc`）だけを載せる。ほかの文書もエクスポートはする |
54
58
  | `-h`, `--help` | ヘルプを表示する |
55
59
  | `-v`, `--version` | バージョンを表示する |
56
60
 
57
- フォルダはサブフォルダも含めて `*.md` と `*.markdown` を探します（`node_modules` とドットで始まるフォルダは除く）。紐付けの警告は標準エラーに出します（GitHub Actions では注釈になります）。
61
+ フォルダはサブフォルダも含めて `*.md` と `*.markdown` を探します（`node_modules` とドットで始まるフォルダは除く）。紐付けの警告と表のオプションの警告は標準エラーに出します（GitHub Actions では注釈になります）。
58
62
 
59
- 文書を書き出せなかったとき、mermaid が描画できない図があったとき（HTML は書き出します）、`--strict` で紐付けの警告があったときは終了コード 1、コマンドラインの誤りは 2 で終わります。
63
+ 文書を書き出せなかったとき（`--diff-base` で、不明なリビジョンなどで git が失敗したときも）、mermaid が描画できない図があったとき（HTML は書き出します）、`--strict` で警告があったときは終了コード 1、コマンドラインの誤りは 2 で終わります。
60
64
 
61
65
  ## GitHub Actions
62
66
 
@@ -73,6 +77,15 @@ md-design-doc export docs -o site
73
77
  path: site
74
78
  ```
75
79
 
80
+ `--diff-base` で前回のリリースからの差分を表示するには、`actions/checkout` が既定では取得しない履歴も取得します。
81
+
82
+ ```yaml
83
+ - uses: actions/checkout@v4
84
+ with:
85
+ fetch-depth: 0 # 比較するタグやコミット
86
+ - run: npx markdown-design-doc-viewer export docs -o site --index --diff-base v1.0
87
+ ```
88
+
76
89
  ## 書き方
77
90
 
78
91
  図の中に `%% @link-headings` を書くと、その図が後ろの見出しと紐付きます。矢印・ノードと見出しは文言で、または `%% @ref` で対応付けます。記法は [書き方](https://github.com/playree/markdown-design-doc-viewer/blob/main/README.ja.md#書き方) を、AI アシスタントにこの形式で書かせるには [AI 向けの記法ガイド](https://github.com/playree/markdown-design-doc-viewer/blob/main/docs/ai-authoring-guide.ja.md) を参照してください。ガイドとこのコマンドの使い方は Agent Skill の [markdown-design-doc-skill.zip](https://github.com/playree/markdown-design-doc-viewer/releases/latest/download/markdown-design-doc-skill.zip) にもしてあります。
package/README.md CHANGED
@@ -12,13 +12,14 @@ The HTML is the same as the VS Code extension's `Export Design Doc as HTML` comm
12
12
 
13
13
  ![Sequence diagram on the left, linked step descriptions on the right](https://raw.githubusercontent.com/playree/markdown-design-doc-viewer/main/images/screenshot.png)
14
14
 
15
- **[Live sample](https://playree.github.io/markdown-design-doc-viewer/)**: an HTML file written by this command from [examples/screenshot.md](https://github.com/playree/markdown-design-doc-viewer/blob/main/examples/screenshot.md).
15
+ **[Live sample](https://playree.github.io/markdown-design-doc-viewer/sample/)**: an HTML file written by this command from [examples/screenshot.md](https://github.com/playree/markdown-design-doc-viewer/blob/main/examples/screenshot.md).
16
16
 
17
17
  ## Usage
18
18
 
19
19
  ```sh
20
20
  npx markdown-design-doc-viewer export docs -o site # all the Markdown files under docs/ to site/docs/*.html
21
21
  npx markdown-design-doc-viewer export docs -o site --index # plus site/index.html, a list of the documents
22
+ npx markdown-design-doc-viewer export docs -o site --diff-base v1.0 # with their changes since the tag v1.0
22
23
  npx markdown-design-doc-viewer export README.md # README.html next to it
23
24
  ```
24
25
 
@@ -47,16 +48,19 @@ md-design-doc export docs -o site
47
48
  | `--no-heading-numbers` | Do not show the arrow numbers (`autonumber`) at the start of the linked headings. |
48
49
  | `--no-front-matter` | Hide the YAML front matter (shown as a table of metadata, or as a header with `type: design_doc`). |
49
50
  | `--no-sticky-table-header` | Do not keep the header row of a long table at the top while scrolling. |
51
+ | `--no-table-tree-highlight` | Do not highlight the parents and children of the row under the pointer in the tables shown as trees (`level=` of the table options). |
50
52
  | `--chrome <path>` | Chrome or Chromium to render the diagrams with. |
51
- | `--strict` | Fail when a document has a link warning (a broken `@ref` or a misplaced marker). Arrows and headings that are only not linked do not fail. |
52
- | `--index` | Also write `index.html` in `--out-dir` (required), a list of the exported documents: a table for each folder, with their title (linked), file name, and the `version`, `product`, `status` and `updated` of their front matter. |
53
+ | `--strict` | Fail when a document has a warning: a link warning (a broken `@ref` or a misplaced marker), or table options that cannot be applied. Arrows and headings that are only not linked do not fail. |
54
+ | `--diff-base <rev>` | Show the changes of each document since the git revision `<rev>` (a tag, a commit or a branch), as the VS Code extension shows its differences from a revision: the blocks added, changed and deleted are marked with green, blue and red bands, the words changed are highlighted, and the old version of a changed diagram is shown folded below it. A bar at the bottom of the page goes from one change to the next, and hides or shows them. A document the revision does not have at its path (added or renamed since) is shown as all added. Requires git, and the history of the revision in the clone (see [GitHub Actions](#github-actions)). With `--index`, the list has a column of the changes of each document. |
55
+ | `--index` | Also write `index.html` in `--out-dir` (required), a list of the exported documents: a table for each folder, with their title (linked), file name, and the `version`, `product`, `status` and `updated` of their front matter. The page has a search box that filters the documents, and its column headers sort them. |
53
56
  | `--index-title <title>` | Title of `index.html`. Default: `Design Docs` (`設計書一覧` with `--lang ja`). |
57
+ | `--index-design-docs` | List only the design docs (`type: design_doc` in their front matter) in `index.html`. The other documents are still exported. |
54
58
  | `-h`, `--help` | Show the help. |
55
59
  | `-v`, `--version` | Show the version. |
56
60
 
57
- Folders are searched for `*.md` and `*.markdown` files, including their subfolders, except `node_modules` and folders starting with a dot. Link warnings are written to the standard error (as annotations in GitHub Actions).
61
+ Folders are searched for `*.md` and `*.markdown` files, including their subfolders, except `node_modules` and folders starting with a dot. Link warnings and the warnings of table options are written to the standard error (as annotations in GitHub Actions).
58
62
 
59
- 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.
63
+ The exit status is 1 when a document could not be exported (also when git fails with `--diff-base`, e.g. for an unknown revision) or has a diagram mermaid cannot render (its HTML is written anyway), or with `--strict` a warning, and 2 for a wrong command line.
60
64
 
61
65
  ## GitHub Actions
62
66
 
@@ -73,6 +77,15 @@ For example, to publish the documents of a repository as an artifact of each bui
73
77
  path: site
74
78
  ```
75
79
 
80
+ To show the changes since the last release with `--diff-base`, check out the history, which `actions/checkout` leaves out by default:
81
+
82
+ ```yaml
83
+ - uses: actions/checkout@v4
84
+ with:
85
+ fetch-depth: 0 # the tags and commits to compare with
86
+ - run: npx markdown-design-doc-viewer export docs -o site --index --diff-base v1.0
87
+ ```
88
+
76
89
  ## Writing linked documents
77
90
 
78
91
  A diagram is linked to the headings after it with `%% @link-headings` in the diagram; arrows and nodes are matched with the headings by their text, or with `%% @ref`. See [Writing linked documents](https://github.com/playree/markdown-design-doc-viewer#writing-linked-documents) for the syntax, and the [authoring guide for AI](https://github.com/playree/markdown-design-doc-viewer/blob/main/docs/ai-authoring-guide.md) to have an AI assistant write documents in this format. The guide and the usage of this command are also packaged as an Agent Skill: [markdown-design-doc-skill.zip](https://github.com/playree/markdown-design-doc-viewer/releases/latest/download/markdown-design-doc-skill.zip).