markdown-design-doc-viewer 0.0.0-stage → 0.5.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,79 @@
+# markdown-design-doc-viewer
+
+[![npm](https://img.shields.io/npm/v/markdown-design-doc-viewer.svg)](https://www.npmjs.com/package/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)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/playree/markdown-design-doc-viewer/blob/main/LICENSE)
+
+[English](https://github.com/playree/markdown-design-doc-viewer/blob/main/docs/cli.md) | 日本語
+
+[Markdown 設計書ビューア](https://github.com/playree/markdown-design-doc-viewer/blob/main/README.ja.md)のコマンドライン版です。Markdown で書いた設計書を、CI やバッチ処理で VS Code なしに 1 つの HTML ファイルへ書き出します。
+
+書き出す HTML は VS Code 拡張の `設計書を HTML にエクスポート` コマンドと同じです。**mermaid のシーケンス図やフローチャートと処理概要を横並びにして**表示し、図の矢印（フローチャートではノード）と見出しが紐付いて、マウスを載せたりクリックしたりするとハイライトします。図はヘッドレス Chrome で描画し、ローカルの画像は埋め込むので、どのブラウザでも開けて、印刷から PDF にもできます。
+
+![左にシーケンス図、右に紐付いた処理概要](https://raw.githubusercontent.com/playree/markdown-design-doc-viewer/main/images/screenshot.ja.png)
+
+## 使い方
+
+```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 を
+```
+
+プロジェクトにインストールした場合（`npm install --save-dev markdown-design-doc-viewer`）、コマンド名は `md-design-doc` です。
+
+```sh
+md-design-doc export docs -o site
+```
+
+## 必要なもの
+
+- 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`（既定。mermaid の標準で、フローチャートのノードに影が付く）か `classic`（影のない平坦な見た目） |
+| `--split-min-width <px>` | 図と処理概要を横並びにする最小のウィンドウ幅 (px)。既定は `1000` |
+| `--full-width` | 本文を最大 1280px の中央の列に収めない |
+| `--no-heading-numbers` | 紐付いた見出しの先頭に矢印の番号（`autonumber`）を表示しない |
+| `--no-front-matter` | YAML front matter（メタ情報の表、`type: design_doc` ではヘッダ）を表示しない |
+| `--no-sticky-table-header` | 長い表のヘッダ行をスクロール中に上端に固定しない |
+| `--chrome <path>` | 図の描画に使う Chrome か Chromium |
+| `--strict` | 紐付けの警告（壊れた `@ref` や置き場所の誤ったマーカーなど）があれば失敗にする。紐付いていないだけの矢印・見出しでは失敗しない |
+| `-h`, `--help` | ヘルプを表示する |
+| `-v`, `--version` | バージョンを表示する |
+
+フォルダは `*.md` と `*.markdown` を探します（`node_modules` とドットで始まるフォルダは除く）。紐付けの警告は標準エラーに出します（GitHub Actions では注釈になります）。
+
+文書を書き出せなかったとき、mermaid が描画できない図があったとき（HTML は書き出します）、`--strict` で紐付けの警告があったときは終了コード 1、コマンドラインの誤りは 2 で終わります。
+
+## GitHub Actions
+
+たとえば、リポジトリの設計書をビルドごとに成果物として公開するには:
+
+```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
+```
+
+## 書き方
+
+図の中に `%% @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) を参照してください。
+
+エディタとプレビューを同期させながら書くには、[VS Code 拡張](https://marketplace.visualstudio.com/items?itemName=playree.markdown-design-doc-viewer)を使ってください。
+
+## ライセンス
+
+[MIT](https://github.com/playree/markdown-design-doc-viewer/blob/main/LICENSE)

package/README.md

@@ -1,3 +1,79 @@
-# 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.
+[![npm](https://img.shields.io/npm/v/markdown-design-doc-viewer.svg)](https://www.npmjs.com/package/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)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/playree/markdown-design-doc-viewer/blob/main/LICENSE)
+
+English | [日本語](https://github.com/playree/markdown-design-doc-viewer/blob/main/docs/cli.ja.md)
+
+The command line of [Markdown Design Doc Viewer](https://github.com/playree/markdown-design-doc-viewer), to export design documents written in Markdown to single HTML files, in CI or in a batch, without VS Code.
+
+The HTML is the same as the VS Code extension's `Export Design Doc as HTML` command writes: **mermaid sequence diagrams and flowcharts are shown side by side with their step descriptions**, and each arrow (or flowchart node) is linked to its heading, highlighted when hovered or clicked. The diagrams are rendered with headless Chrome and local images are embedded, so the file can be opened in any browser or printed to PDF.
+
+![Sequence diagram on the left, linked step descriptions on the right](https://raw.githubusercontent.com/playree/markdown-design-doc-viewer/main/images/screenshot.png)
+
+## Usage
+
+```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
+```
+
+Installed in a project (`npm install --save-dev markdown-design-doc-viewer`), the command is `md-design-doc`:
+
+```sh
+md-design-doc export docs -o site
+```
+
+## Requirements
+
+- Node.js 22 or later.
+- 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).
+- For documents in Japanese or other CJK languages, a font for them (`fonts-noto-cjk` on Debian / Ubuntu), or their diagrams are drawn with boxes.
+
+## Options
+
+| 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 (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>` | Look of the diagrams: `neo` (default, mermaid's, with shadows on flowchart nodes) or `classic` (flat). |
+| `--split-min-width <px>` | Minimum window width (px) for the diagrams beside their steps. Default: `1000`. |
+| `--full-width` | Do not keep the text in a centered column up to 1280px wide. |
+| `--no-heading-numbers` | Do not show the arrow numbers (`autonumber`) at the start of the linked headings. |
+| `--no-front-matter` | Hide the YAML front matter (shown as a table of metadata, or as a header with `type: design_doc`). |
+| `--no-sticky-table-header` | Do not keep the header row of a long table at the top while scrolling. |
+| `--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). Arrows and headings that are only not linked do not fail. |
+| `-h`, `--help` | Show the help. |
+| `-v`, `--version` | Show the version. |
+
+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.
+
+## GitHub Actions
+
+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
+```
+
+## 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.
+
+To preview the documents while writing them, with the editor and the preview in sync, use the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=playree.markdown-design-doc-viewer).
+
+## License
+
+[MIT](https://github.com/playree/markdown-design-doc-viewer/blob/main/LICENSE)

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.