コマンドオプション
monodocs は 1 つの CLI に init・build・watch・serve・validate の 5 つのサブコマンドを持ちます。文書を読む 4 つは省略可能な入力引数と設定ファイルオプションを共有し、それぞれ固有のオプションを少し持ちます。init はそのどちらも取りません。
monodocs <command> [input] [options][input] は走査する入力ディレクトリ、または単一のソースファイル（既定: ./docs）です。ファイルを渡すと、そのファイル 1 ページだけを束ね、リンク・画像・monodocs.config.yml の基準はそれを含むディレクトリになります。CLI オプションは常に設定ファイルより優先されます。マージ順序や monodocs.config.yml の探索場所は 設定ファイル を参照してください。
TIP
ソースから実行する場合は monodocs を node packages/cli/dist/index.js（必要に応じて scripts/app.sh 経由）に読み替えてください。はじめに を参照。
グローバルオプション
| オプション | 説明 |
|---|---|
-V, --version | バージョンを表示して終了します。 |
-h, --help | コマンドのヘルプを表示して終了します。 |
--lang <lang> | monodocs 自身のメッセージの言語。en（既定）または ja。下記参照。 |
monodocs --help # トップレベルのヘルプ（全コマンド一覧）
monodocs build --help # 個別コマンドのヘルプメッセージの言語
monodocs が印字するもの（--help、エラー、警告）は既定で英語です。日本語は、コマンド単位またはシェルや CI ジョブ全体で選びます。
monodocs --lang ja build ./docs
MONODOCS_LANG=ja monodocs build ./docs- フラグが環境変数に優先し、環境変数が既定に優先します。
- 対応していない値は、対応する値を挙げて拒否します。黙って英語へフォールバックすることはありません。
LANG/LC_ALLは意図的に見ません。ビルドログが、それを作ったマシンに依存しないようにするためです。- 設定ファイルの
langとは別物です。あちらはビルドされる文書を記述し、ビルドしている端末は記述しません。
NOTE
依存パッケージのメッセージが包まれずに届くもの（Zod のスキーマエラー本体、Puppeteer のスタックトレース）は、その依存パッケージの言語のままです。monodocs が包んでいるものは、その包み側を訳します。よくある引数パーサのエラー（不明なオプション・不明なコマンド・引数の欠落）は訳します。組み立て直せない稀なものはパーサの文言のまま出します。
init
出発点になる設定ファイルと最初のページを書き出します。入力引数も設定ファイルオプションも持たない唯一のサブコマンドです。
monodocs init| 書き出すもの | 内容 |
|---|---|
monodocs.config.yml | コメント付きの短い出発点（title・lang・input・output）。他のキーは既定値のままです。残りは 設定ファイル にあります。 |
docs/index.md | 最初のページ。既定の input が指す場所に置かれます。 |
書き出したものは手を入れずにビルドできるので、最初のビルドにもオプションは要りません。
monodocs init
monodocs build # -> dist/docs.html上書きはしません。 どちらかのファイルが既にある場合はどちらも書かず、見つかったものをすべて名指しして終了コード 1 で終わります。既にある docs/ ディレクトリは問題なく、ページはそこにあるものの隣に置かれます。
雛形は メッセージの言語 に従います（コメント、最初のページの文章、設定する lang の値）。そのため monodocs --lang ja init は lang: "ja" の下に日本語の最初のページを書き出します。それ以外では 2 つの設定は独立で、書き出されるファイルの lang の位置にもそう書いてあります。別の言語で書くときは、その 1 行を書き換えてください。
build
ドキュメントをビルドして単一の自己完結ファイルを生成します。HTML、PDF、またはその両方（--format）です。
monodocs build [input] [options]| 引数 / オプション | 既定値 | 説明 |
|---|---|---|
[input] | ./docs | 走査する入力ディレクトリ、または単一のソースファイル。 |
-o, --output <file> | ./dist/docs.html | 出力ファイルパス。output.path を上書き。 |
-c, --config <file> | 自動検出 | 設定ファイル。monodocs.config.yml があれば使用。 |
-f, --format <format> | html | 出力形式: html | pdf | both。output.format を上書き。 |
--diff-from <ref> | — | git の ref で指定した以前の版との差分を HTML に書き込む。下記を参照。 |
--diff-from-dir <dir> | — | 以前の版との差分を HTML に書き込む。以前の版は、現在のディレクトリに当たるディレクトリから読む。下記を参照。 |
# ./docs を ./dist/docs.html にビルド
monodocs build
# 入力と出力を明示
monodocs build ./docs -o ./dist/docs.html
# 設定ファイルを明示
monodocs build ./docs -c ./monodocs.config.yml
# 単一ファイルを 1 ページの文書として出力する
monodocs build ./docs/plan.md --format pdf -o ./dist/plan.pdf成功すると生成ページ数と出力パスを表示します。警告（リンク切れ・タイトル欠落など）は表示されますがビルドは失敗しません。エラーで失敗させたいときは validate を、警告でも失敗させたいときは validate --strict を使います。唯一の例外は fontCheck: error で、そのマシンにフォントが無い文字を成果物が抱えることになるビルドを止めます。
以前の版との差分
改訂した文書を渡すとき、--diff-from と --diff-from-dir は、以前の版との差分を書き込んだ HTML をビルドします。Git を見ない読み手のためのものです。差分のサンプルを見てください。
# 以前の版を git のタグ、ブランチ、コミットで指定する
monodocs build ./docs -o ./dist/docs.html --diff-from v1.2
# 以前の版をディレクトリで指定する
monodocs build ./docs -o ./dist/docs.html --diff-from-dir ../project-1.2読み手が得るもの：
- 変更の一覧：文書を開くと最初に出るページです。
html.diffViewDefaultで片方の版の表示で開くときは、その版の最初のページが出ます。追加、移動、変更、削除されたページをそれぞれのページへのリンクで並べ、変わっていないページの数を添えます。タイトルは 2 つの版をそれぞれのdocument.versionで示します。それを持たない以前の版は、書いたとおりの引数（v1.2、../project-1.2）で示します。 - 変わったページの左右での比較：左に以前のページ、右に新しいページを並べ、共通する部分の高さを揃えます。削除されたブロックは左の列で、追加されたブロックは右の列で印が付きます。変わっていないページは 1 つだけ出ます。削除されたページは、以前の版のサイドバーでいた場所に 1 つのページとして出て、追加されたページには注記が付きます。
- 1 列の表示（Inline）：新しい版に、削除されたブロックをもといた場所に取り消し線付きで書き戻し、追加されたブロックには下線を付けます。変更履歴のように、1 つの文書として通して読めます。ブロックの中を比べるのは後のリリースなので、それまでは 1 語だけ変えたブロックも、以前のブロックの後ろに新しいブロックが続く形で読めます。
- 上端に固定されたバー：4 つの表示——左右で比較（Side by side）、1 列（Inline）、以前の版（Earlier version）、新しい版（New version）——と、すべての変更を数を示しながら順にたどる前後のボタンを持ちます。片方の版の表示は、その版をプレーンに見せます。Show changes で、その版の変更に印が付きます。検索は表示が読む版を対象にします。以前の版の表示では以前の版、それ以外では新しい版です。文書は左右で比較する表示か、
html.diffViewDefaultが指す表示で開きます。読者が選んだ表示は保存しません。 - サイドバー：追加されたページを緑と
+、削除されたページを赤と−、変更されたページをオレンジと•、移動したページを青と→で示します。片方の版の表示では、その版のサイドバーになります。
ブロックは読んだときの内容で比べます。リンク先、強調、表の枠、ビルドが振る番号（節、図、脚注）は差分になりません。新しい route に移したページは aliases で対応付けます。そうしなければ削除と追加になります。
以前の版の見つけ方。 2 つの版はどちらもこの monodocs でビルドし、以前の版はそれ自身のソースから組みます。
--diff-from <ref>は、その ref をチェックアウトしたときに得られるファイルを、現在のディレクトリがあるリポジトリから読みます。作業ツリー、インデックス、ref には触れません。PATHにgitが必要で、CI では履歴も要ります。fetch-depth: 0でチェックアウトしてください。LFS に置いたファイルには git-lfs が要り、ページ、include、画像が LFS のポインタのまま出てくるとdiff/lfs-pointerになります。サブモジュールは、--recurse-submodulesを付けないチェックアウトと同じく空で出ます。--diff-from-dir <dir>は、入力ではなく現在のディレクトリに当たる以前の版のディレクトリを指します。プロジェクトのルートで./docsを入力として実行すると、--diff-from-dir ../project-1.2は../project-1.2/docsを読みます。入力の引数と-cも同じように読み替えます。出力での名前は書いたとおりのパスなので、相対パスかdocument.versionを使ってください。- 以前の版は、文書が何を含むか——
input、root、sources.*、sidebar.mode、sidebar.items、sidebar.titleFrom、sidebar.titleTransform、sidebar.flattenSingleChild、math.enabled、mermaid.enabled——を自分の設定から取り、出力の見た目は新しい版の設定に従います。以前の版に無いパスや、以前の版の外に出るパスはdiff/outside-versionになります。文書のディレクトリをあとで改名した版は、新しい版と同じ配置にした写しを--diff-from-dirで渡してください。 - 以前の版のビルドが出す警告は報告しません。リリースした版は直せないからです。以前の版のビルドのエラーはビルドを止めます。
2 つのオプションは同時に使えず（diff/conflicting-options）、build にだけあり、設定ファイルのキーはありません。何と比べるかはビルドに属するからです。差分をどう見せるかは文書に属し、キー html.diffViewDefault で決めます。差分は今のところ HTML だけです。-f pdf、-f both、output.format のどれで PDF を出力しても、ビルドは diff/unsupported で止まります。バー、一覧、注記の文言は、ほかの UI ラベルと同じく lang に従い（英語、lang: ja なら日本語）、html.labels で変えられます。サイズの報告には 差分 の行が加わります。
watch
入力・設定ファイルの変更を検知するたびに再ビルドします。出力は書き出しますが配信はしません。プレビューサーバが必要なら serve を使います。
monodocs watch [input] [options]| 引数 / オプション | 既定値 | 説明 |
|---|---|---|
[input] | ./docs | 監視する入力ディレクトリ、または単一のソースファイル。 |
-o, --output <file> | ./dist/docs.html | 出力ファイルパス。output.path を上書き。 |
-c, --config <file> | 自動検出 | 設定ファイル。monodocs.config.yml があれば使用。 |
出力ファイルへの書き込みイベントは無視するため、再ビルドが自分自身を再トリガすることはありません。Ctrl+C で停止します。
NOTE
Linux では、監視に inotify のインスタンスを 1 つ使います。利用者 1 人が持てる数（fs.inotify.max_user_instances、多くは 128）は、エディタやブラウザを含め、その人が動かすすべてのプログラムで分け合います。残りが無いと、watch と serve は EMFILE: too many open files, watch で止まります。上限は cat /proc/sys/fs/inotify/max_user_instances で確かめ、sudo sysctl fs.inotify.max_user_instances=1024 で引き上げます。再起動後も保つには、/etc/sysctl.d/ の下のファイルに fs.inotify.max_user_instances = 1024 と書きます。ホストの利用者と同じ UID で動かす Docker のコンテナ（このリポジトリの開発用スクリプトはそうしています）は、その利用者と上限を分け合います。監視はさらに、入力の下のディレクトリとファイルごとに inotify の watch を 1 つずつ、別の上限 fs.inotify.max_user_watches から使います。それが残っていないと木の一部が監視されません。報告されるのは、監視が始まった後に失敗したもの（後から足したディレクトリなど）だけで、監視を組み立てている間に失敗したものは気づかれません。入力の下の変更を取りこぼすときは、この上限も引き上げてください。
serve
出力を HTTP で配信し、変更を監視して、ブラウザをライブリロード（Server-Sent Events）します。
monodocs serve [input] [options]| 引数 / オプション | 既定値 | 説明 |
|---|---|---|
[input] | ./docs | 配信する入力ディレクトリ、または単一のソースファイル。 |
-o, --output <file> | ./dist/docs.html | 出力ファイルパス。output.path を上書き。 |
-c, --config <file> | 自動検出 | 設定ファイル。monodocs.config.yml があれば使用。 |
-p, --port <port> | 4173 | 待ち受けポート番号。 |
-H, --host <host> | 127.0.0.1 | バインドするホスト。マシン外（例: Docker ホスト）から接続を受けるには 0.0.0.0 を指定。 |
--open | 無効 | 起動時に既定のブラウザで配信 URL を開きます。 |
# ./docs を http://127.0.0.1:4173/ で配信
monodocs serve
# 全インターフェースにバインド（例: Docker ホストから見る）してブラウザを開く
monodocs serve ./docs --host 0.0.0.0 --openCtrl+C で停止します。
validate
リンク切れ・画像欠落・タイトル欠落・見出しレベルの飛び・alt 属性の無い画像を、出力を書き出さずに 検出します。CI 向けです。
monodocs validate [input] [options]| 引数 / オプション | 既定値 | 説明 |
|---|---|---|
[input] | ./docs | 検証する入力ディレクトリ、または単一のソースファイル。 |
-c, --config <file> | 自動検出 | 設定ファイル。monodocs.config.yml があれば使用。 |
--format <format> | human | 報告の形式。human または json。 |
--strict | 無効 | エラーだけでなく警告でも失敗させる。 |
monodocs validate ./docsエラーと警告は標準エラー出力に表示されます。エラー が見つかったときに終了コード 1 で終了します。警告だけなら 0 のままで、⚠ 警告 2 件（20 ページ）。エラーはありません。 と表示します。--strict を付けると警告でも失敗します。
monodocs validate ./docs # エラーで失敗し、警告は報告する
monodocs validate ./docs --strict # 警告でも失敗する終了コードは報告の severity に従うため、リリースで検査が警告として増えても、通っていたジョブは失敗しません。警告をリリースのゲートにするには、ワークフローで --strict を付けてください。
validate はビルドと同じパイプラインを走らせるので、validate が報告する検査はすべてビルドも報告します（ビルドはそのうえで出力も書き出します）。逆は成り立ちません。PDF を書き出すビルドは、ページ番号の帯に対して下余白が足りない、このマシンのどのフォントも描けない文字がある、といったその作業でしか分からないことも報告します。
NOTE
Mermaid はブラウザなしで検証するため、pre-render の実描画や図の構文エラーは validate では検査されません。
ジョブが読める報告
--format json は JSON オブジェクトを 1 つだけ標準出力に出し、ほかには何も出さないので、ワークフローはそのまま解析できます。
monodocs validate ./docs --format json{
"schemaVersion": 1,
"diagnostics": [
{
"code": "link/unresolved",
"severity": "warning",
"message": "Unresolved link \"nope.md\" in \"index.md:3\".",
"path": "index.md",
"line": 3
}
]
}schemaVersionはジョブが解析する形が変わったときだけ変わります。リリースは形を変えずに検査とコードを増やせます。固定するのは monodocs のバージョンではなくschemaVersionです。codeは安定しています。link/unresolvedはこれからもまさにそれを指すので、ジョブはこれで絞り込めます。pathは入力ディレクトリからの相対パス、lineは monodocs が知っている場合に入ります。
WARNING
message に一致させないでください。人が読む文で、--lang で翻訳され、リリースをまたいで書き直されます。