markdown-design-doc-viewer 1.1.0 → 1.2.0

package/README.ja.md

@@ -19,6 +19,7 @@
 ```sh
 npx markdown-design-doc-viewer export docs -o site     # docs/ 以下の Markdown をすべて site/docs/*.html に
 npx markdown-design-doc-viewer export docs -o site --index   # 加えて文書の一覧を site/index.html に
+npx markdown-design-doc-viewer export docs -o site --diff-base v1.0   # タグ v1.0 からの差分付きで
 npx markdown-design-doc-viewer export README.md        # 隣に README.html を
 ```
 
@@ -50,6 +51,7 @@ md-design-doc export docs -o site
 | `--no-table-tree-highlight` | ツリーとして表示する表（表のオプションの `level=`）で、マウスを乗せた行の親と子をハイライトしない |
 | `--chrome <path>` | 図の描画に使う Chrome か Chromium |
 | `--strict` | 警告（壊れた `@ref` や置き場所の誤ったマーカーなどの紐付けの警告、適用できない表のオプション）があれば失敗にする。紐付いていないだけの矢印・見出しでは失敗しない |
+| `--diff-base <rev>` | 各文書の、git のリビジョン `<rev>`（タグ・コミット・ブランチ）からの差分を表示する。VS Code 拡張の履歴との比較と同じく、追加・変更・削除したブロックに緑・青・赤の帯を付け、変わった語を強調し、変更した図には変更前の図を折りたたんで添える。ページ下部のバーで前後の変更へ移動したり、差分を隠したり表示したりできる。そのリビジョンの同じパスにない文書（その後に追加・名前を変更したもの）は全体を追加として表示する。git と、クローンにそのリビジョンまでの履歴が必要（[GitHub Actions](#github-actions) を参照）。`--index` と使うと、一覧に各文書の差分の列が付く |
 | `--index` | 書き出した文書の一覧を `--out-dir`（必須）の `index.html` にも書き出す。フォルダごとの表に、タイトル（リンク）・ファイル名と、front matter の `version`・`product`・`status`・`updated` を載せる。ページの検索欄で文書を絞り込め、列見出しで並べ替えられる |
 | `--index-title <title>` | `index.html` のタイトル。既定は `Design Docs`（`--lang ja` では `設計書一覧`） |
 | `--index-design-docs` | `index.html` に設計書（front matter に `type: design_doc`）だけを載せる。ほかの文書もエクスポートはする |
@@ -58,7 +60,7 @@ md-design-doc export docs -o site
 
 フォルダはサブフォルダも含めて `*.md` と `*.markdown` を探します（`node_modules` とドットで始まるフォルダは除く）。紐付けの警告と表のオプションの警告は標準エラーに出します（GitHub Actions では注釈になります）。
 
-文書を書き出せなかったとき、mermaid が描画できない図があったとき（HTML は書き出します）、`--strict` で警告があったときは終了コード 1、コマンドラインの誤りは 2 で終わります。
+文書を書き出せなかったとき（`--diff-base` で、不明なリビジョンなどで git が失敗したときも）、mermaid が描画できない図があったとき（HTML は書き出します）、`--strict` で警告があったときは終了コード 1、コマンドラインの誤りは 2 で終わります。
 
 ## GitHub Actions
 
@@ -75,6 +77,15 @@ md-design-doc export docs -o site
     path: site
 ```
 
+`--diff-base` で前回のリリースからの差分を表示するには、`actions/checkout` が既定では取得しない履歴も取得します。
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0   # 比較するタグやコミット
+- run: npx markdown-design-doc-viewer export docs -o site --index --diff-base v1.0
+```
+
 ## 書き方
 
 図の中に `%% @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

@@ -19,6 +19,7 @@ The HTML is the same as the VS Code extension's `Export Design Doc as HTML` comm
 ```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 docs -o site --index   # plus site/index.html, a list of the documents
+npx markdown-design-doc-viewer export docs -o site --diff-base v1.0   # with their changes since the tag v1.0
 npx markdown-design-doc-viewer export README.md        # README.html next to it
 ```
 
@@ -50,6 +51,7 @@ md-design-doc export docs -o site
 | `--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). |
 | `--chrome <path>` | Chrome or Chromium to render the diagrams with. |
 | `--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. |
+| `--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. |
 | `--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. |
 | `--index-title <title>` | Title of `index.html`. Default: `Design Docs` (`設計書一覧` with `--lang ja`). |
 | `--index-design-docs` | List only the design docs (`type: design_doc` in their front matter) in `index.html`. The other documents are still exported. |
@@ -58,7 +60,7 @@ md-design-doc export docs -o site
 
 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).
 
-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 warning, and 2 for a wrong command line.
+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.
 
 ## GitHub Actions
 
@@ -75,6 +77,15 @@ For example, to publish the documents of a repository as an artifact of each bui
     path: site
 ```
 
+To show the changes since the last release with `--diff-base`, check out the history, which `actions/checkout` leaves out by default:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0   # the tags and commits to compare with
+- run: npx markdown-design-doc-viewer export docs -o site --index --diff-base v1.0
+```
+
 ## Writing linked documents
 
 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).