コマンド・引数・出力・終了コードの一覧
どのコマンドも npx github:shuhei1101/mdmark#v{版} {コマンド} で呼ぶ。
{版} は使う版の {MAJOR}.{MINOR}.{PATCH}。
npm のレジストリには公開しない。
Node 24 以降で動く。
export・build・check・upgrade は、--config で指した設定ファイルか、今のフォルダから上のフォルダへ順に探して最初に見つかった mdmark.config.yaml を読む。
設定のキーは 設定。
| 名前 | コマンド | 説明 |
|---|---|---|
| 雛形を置く | mdmark init |
設定・使う側の CSS・索引・拡張の雛形をフォルダに置く |
| 文書を HTML に書き出す | mdmark export |
Markdown を 1 つ、CDN を読まない 1 枚の HTML に書き出す |
| 複数の文書を 1 枚の HTML にまとめる | mdmark build |
設定の build で決めた文書を、文書を行き来できる 1 枚の HTML にまとめる |
| 設定と索引を点検する | mdmark check |
設定の形・索引と文書のずれ・build の対象の有無を点検する |
| 版を上げる | mdmark upgrade |
手元の版から呼んだ CLI の版までの移行の手順を版の順に当て、その範囲の変更履歴を出す |
| MCP サーバーを起動する | mdmark serve |
Claude Code のプラグインがつなぐ MCP の常駐サーバーを、127.0.0.1 の HTTP で起動する |
設定・使う側の CSS・索引・拡張の雛形をフォルダに置く。 既にあるファイルは上書きしない。 手順は 雛形を置く。
置いたファイルの行（置いた: {パス}）と、既にあって置かなかったファイルの行（置かなかった（既にある）: {パス}）を、雛形の並びで 1 行ずつ標準出力に出す。
パスは置く先のフォルダからの相対パス。
置かなかった（既にある）: mdmark.config.yaml
置いた: theme.css
置いた: index.yaml
置いた: extensions/example.ts
置いた: tsconfig.json
置いた: package.json
npx github:shuhei1101/mdmark#v{版} init [{置く先のフォルダ}] [--js]
| 引数 | 必須 / 任意 | 説明 | 例 |
|---|---|---|---|
{置く先のフォルダ} |
任意 | 雛形を置くフォルダ。省くと今のフォルダ。無ければ作る | docs |
--js |
任意 | 拡張の雛形を JavaScript で置く。extensions/example.js を置き、tsconfig.json と package.json は置かない |
--js |
| コード | 意味 |
|---|---|
0 |
置けた（置かなかったファイルがあっても） |
1 |
置く先のフォルダを作れない、またはファイルを書けない。標準エラーに書けなかったパスと直し方を出す。書けたファイルは残る |
Markdown を 1 つ、CDN を読まない 1 枚の HTML に書き出す。
配布物・使う側の CSS・外部ライブラリのモジュール・拡張・画像を埋める。
開いた HTML は mount で文書を描き、開いてから描き終えるまで、ページ自身と blob:・data: のほかへ要求しない。
手順は 文書を書き出す。
標準出力に 書き出した: {出力のパス} の 1 行を出す。
警告は、標準エラーに 1 つ 1 行（警告: {ファイル}: {内容}）で出す。
警告の対象は、読めない画像・外部ライブラリのモジュール・拡張・theme の CSS と、埋めずに残した絶対 URL の画像。
文書間のリンクは書いたままの href で残し、警告に出さない。
書き出した: docs/使い方/guide.html
警告: docs/使い方/guide.md: 画像 `img/missing.png` を読めません。パスを直すか画像を置いてください。
npx github:shuhei1101/mdmark#v{版} export {文書} [--out {出力}] [--config {設定ファイル}]
| 引数 | 必須 / 任意 | 説明 | 例 |
|---|---|---|---|
{文書} |
必須 | 書き出す Markdown のパス | docs/使い方/guide.md |
--out |
任意 | 書き出す HTML のパス。省くと文書と同じフォルダの、拡張子を .html に替えたパス。親のフォルダが無ければ作り、既にあれば上書きする |
--out dist/guide.html |
--config |
任意 | 使う設定ファイルのパス。省くと今のフォルダから上のフォルダへ順に mdmark.config.yaml を探す |
--config docs/mdmark.config.yaml |
| コード | 意味 |
|---|---|
0 |
書き出した（警告があっても） |
1 |
設定ファイルが無い・読めない・Schema に合わない（空の設定ファイルを含む）。標準エラーに原因と直し方を出す。Schema に合わないときは mdmark check で確かめられることも出す |
1 |
{文書} のファイルが無い・読めない。標準エラーにパスと直し方を出す |
1 |
出力のパスへ書けない。標準エラーに書けなかったパスと直し方を出す。HTML はどこにも書かない |
設定の build で決めた文書を、文書を行き来できる 1 枚の HTML にまとめる。
参照・被参照・用語のツールチップが効く。
埋めるものと外へ要求しないことは、文書を HTML に書き出す と同じ。
手順は 文書を1枚にまとめる。
標準出力に 書き出した: {build.out}（文書 {件数} 件） の 1 行を出す。
警告は、文書を HTML に書き出す の警告に、まとめた HTML に含まれない文書へのリンクと、build.glossary と build.entry がまとめる文書に当たらないことを足して出す。
書き出した: dist/docs.html（文書 3 件）
警告: README.md: `下書き/メモ.md` へのリンクはまとめた HTML に含まれません。書いたままのリンクで残します。まとめるなら `build.include` に足してください。
npx github:shuhei1101/mdmark#v{版} build [--config {設定ファイル}]
| 引数 | 必須 / 任意 | 説明 | 例 |
|---|---|---|---|
--config |
任意 | 使う設定ファイルのパス。省くと今のフォルダから上のフォルダへ順に mdmark.config.yaml を探す。まとめる文書と書き出す先は、設定の build が持つ |
--config docs/mdmark.config.yaml |
| コード | 意味 |
|---|---|
0 |
build.out に書いた（警告があっても） |
1 |
設定ファイルが無い・読めない・Schema に合わない（空の設定ファイルを含む）、または build が無い。標準エラーに原因と直し方を出す |
1 |
build.include に当たり build.exclude に当たらない文書が 0 件。標準エラーに、対象が 0 件であることと build.include を直すことを出す。HTML は書かない |
1 |
build.out へ書けない。標準エラーに書けなかったパスと直し方を出す |
設定の形・索引と文書のずれ・build の対象の有無・文書の本文にある知らない印を点検する。
ずれの一覧を標準出力に出し、設定・索引・文書は書き換えない。
手順は 点検する。
ずれ 1 つを 1 行（{ファイル}:{場所}: {種類}: {内容}。場所が空のときは {ファイル}: {種類}: {内容}）で並べ、最後に ずれ {件数} 件 の行を出す。
ファイルは設定ファイルのあるフォルダからの相対パス。
並びは schema → no_documents → checkIndex が返した並び → unknown_mark。
内容は、何が合わないかと直し方の日本語の 1 文。
docs/index.yaml:docs[1].path: missing_doc: `old.md` が見つかりません。文書を戻すか、索引の `docs[1]` を消してください。
mdmark.config.yaml:build: schema: `build.out` がありません。書き出す HTML のパスを書いてください。
ずれ 2 件
種類は次のとおり。
| 種類 | 意味 |
|---|---|
schema |
設定か索引が Schema に合わない。build.glossary・build.entry が build.include に当たらないもの、theme・extensions のファイルが無いもの、extensions の拡張を読み込めないものを含む |
no_documents |
build.include に当たり build.exclude に当たらない文書が 0 件 |
missing_doc |
索引にあって、文書が見つからない |
orphan_doc |
文書があって、索引に無い |
broken_ref |
related の id（オブジェクトの要素は to）が索引に無い |
untyped_related |
related の要素が type と when を持たない文字列。オブジェクトへの書き換えを求める |
one_sided_change_together |
change_together の相手が、自分への change_together を記載していない |
related_link_overlap |
change_together でない related の相手を、本文でもリンクしている |
missed_change_together |
--base を渡したとき、change_together の組のうち片方の文書だけが変わっている。場所は空で、ファイルは変わっていない側の文書のパス |
duplicate_term |
用語の語か別名が、NFKC・英字の小文字化・前後の空白の除去で正規化した後に重なっている |
avoided_term |
索引の文書の本文に、用語のやめた言い方が出ている |
duplicate_tag |
タグの語彙の name が重なっている |
tag_alias_conflict |
タグの語彙の aliases が、別のタグの name か aliases と重なっている |
broken_tag_replacement |
タグの語彙の deprecated の振り替え先が、語彙に無い |
unregistered_tag |
文書のタグが、語彙の name にも aliases にも無い。近いタグを添える |
deprecated_tag |
文書のタグが、やめたタグに当たる。振り替え先を添える |
unknown_mark |
文書の本文に、記法の印・features・libraries の対応表・extensions の拡張の印・check.ignore の名前のどれにも当たらない印がある。場所は印のある行の番号 |
missing_doc から deprecated_tag までは、checkIndex が返す kind と同じ（点検が返すずれ）。
タグのずれは、索引がタグの語彙（tags）を記載しているときだけ出る。
missed_change_together は、--base を渡したときだけ出る。
npx github:shuhei1101/mdmark#v{版} check [--config {設定ファイル}] [--base {git の ref}]
| 引数 | 必須 / 任意 | 説明 | 例 |
|---|---|---|---|
--config |
任意 | 使う設定ファイルのパス。省くと今のフォルダから上のフォルダへ順に mdmark.config.yaml を探し、最初に見つかったものを使う |
--config docs/mdmark.config.yaml |
--base |
任意 | 直し忘れの検査に比べる基準の git の ref。渡すと、基準と HEAD の merge-base から作業ツリーまでに変わった文書を比べ、change_together の組のうち片方だけが変わった組を missed_change_together で出す。省くと直し忘れを検査しない。設定に index が無いときは使わない |
--base origin/develop |
| コード | 意味 |
|---|---|
0 |
ずれが 0 件 |
1 |
ずれが 1 件以上ある。全てのずれを出してから終わる |
1 |
--config のファイルが無い、または今のフォルダと上のフォルダに mdmark.config.yaml が無い。標準エラーに、探した場所と mdmark init で置けることを出す |
1 |
設定ファイルを YAML として読めない。標準エラーに、ファイルと読めない行と直し方を出す |
1 |
--base を渡し、git が無い・設定ファイルのフォルダが git のリポジトリの中に無い・ref と HEAD の merge-base を引けない。標準エラーに、渡した ref と引けない理由と、ref を直すか履歴を取得する直し方（CI の checkout の fetch-depth）を出す。ずれの点検はしない |
設定の手元の版から、呼んだ CLI の版（目標の版）までの移行の手順を、設定・索引・文書へ版の順に当てる。 当てた範囲の変更履歴の行を出す。 手順は 版を上げる。仕組みは 版を上げる仕組み。
手元の版より新しく目標の版以下の版の手順を当てる前に、設定ファイルと、手順が書き換えうる全てのファイルの写しを、設定ファイルのあるフォルダの .mdmark/backup/{yyyymmddHHMMSS}/ へ、そのフォルダからの相対パスを保って取る。
.mdmark/ は中身が * の .gitignore を持ち、写しは当てた後も消さない。
全ての手順を当てた後に mdmark check と同じ点検を流し、ずれが 0 件のときだけ設定の version を目標の版に書き換える（無ければ最上位の先頭に足す）。
手順の失敗と点検のずれは、写しから戻して version を変えない。
標準出力に、手元の版: {版}・目標の版: {版} の後、当てる版ごとに {版}: の行と手順 1 つ 1 行（ {種類}: {説明}。壊す手順は種類の後ろに （壊す手順））、変更履歴: の行と変更履歴の行 1 つ 1 行（ {バージョン} {PR} {変更}）を出す。
最後に、当てたときは 写し: {パス} と 版を {目標の版} にしました、--plan のときは --plan のため書き換えていません、当てる手順が無いときは 手元の版が目標の版と同じです。当てる手順はありません を出す。
写しのパスは設定ファイルのあるフォルダからの相対パス。
手順を持たない版は行を出さない。
手元の版: v0.3.0
目標の版: v0.5.0
v0.4.0:
rename_key: `build.out` を `build.output` に改める
v0.5.0:
replace_mark（壊す手順）: 印 `<!-- note -->` を `<!-- callout -->` に書き換える
変更履歴:
v0.4.0 #40 版を上げるときに移行の手順を当てる mdmark upgrade を作る
v0.5.0 #45 注意書きの印の名前を揃える
写し: .mdmark/backup/20261017120000
版を v0.5.0 にしました
npx github:shuhei1101/mdmark#v{目標の版} upgrade [--plan] [--yes] [--config {設定ファイル}]
| 引数 | 必須 / 任意 | 説明 | 例 |
|---|---|---|---|
--plan |
任意 | 何も書き換えず、当てる版ごとの手順・変更履歴の行・壊す手順の有無を出す。写しは取らない | --plan |
--yes |
任意 | 壊す手順を、確かめずに当てる。手元の版と、値を聞く手順の問いは飛ばさない | --yes |
--config |
任意 | 使う設定ファイルのパス。省くと今のフォルダから上のフォルダへ順に mdmark.config.yaml を探し、最初に見つかったものを使う |
--config docs/mdmark.config.yaml |
目標の版は引数で受けず、呼んだ CLI の版にする。
手元の版は設定の version で、無ければ標準エラーに 手元の版（v{MAJOR}.{MINOR}.{PATCH}）を入れてください: を出して聞く（--plan のときも聞く）。
問いへの答えを、問い 1 つにつき 1 行で読む。 問いは次の順に出し、全て書き換えの前に聞く。
version が無いとき）--yes が無く、壊す手順が 1 つ以上あるとき 1 回だけ）。承諾は y だけ--plan は手元の版だけを聞く。
| コード | 意味 |
|---|---|
0 |
手順を当てて点検が通り、version を書き換えた。--plan で示した。手元の版が目標の版と同じで当てる手順が無い |
1 |
壊す手順の確かめに y 以外を答えた。何も書き換えず、写しも取らない。標準エラーに、--yes で確かめずに当てられることを出す |
1 |
手順の途中で、call のスクリプトが 0 以外で終わったか、ファイルを書けなかった。写しから戻し、標準エラーに失敗した版・手順の説明・理由を出す |
1 |
当てた後の点検にずれが 1 件以上ある。写しから戻し、標準エラーに mdmark check と同じ形のずれの行を出す |
1 |
手元の版が目標の版より新しい。標準エラーに、手元の版・目標の版と、npx github:shuhei1101/mdmark#{手元の版} upgrade など手元の版以上の CLI で呼び直すことを出す。何も書き換えない |
1 |
設定の version か問いへの答えが v{MAJOR}.{MINOR}.{PATCH} に合わない。標準エラーに書式を出す |
1 |
問いに答える前に標準入力が終わった。標準エラーに答える問いを出し、何も書き換えない |
1 |
当てる版の steps.yaml が読めない・形に合わない、または call のスクリプトが無い。標準エラーに版と合わないところと、mdmark を入れ直すことを出す。何も書き換えない |
1 |
--config のファイルが無い、今のフォルダと上のフォルダに mdmark.config.yaml が無い、または YAML として読めない。mdmark check と同じ文を標準エラーに出す |
Claude Code のプラグインがつなぐ MCP の常駐サーバーを、127.0.0.1 の Streamable HTTP で起動する。 手順は MCPサーバーを起動する。ツールは MCP。
127.0.0.1 の /mcp だけを待ち受ける。
待ち受けたら、接続先の URL を標準出力に 1 行出し、止める合図を受けるまで動き続ける。
Ctrl+C（SIGINT）か SIGTERM を受けると待ち受けを閉じる。
MCP サーバーを起動しました: http://127.0.0.1:8782/mcp
npx github:shuhei1101/mdmark#v{版} serve
引数は無い。
待ち受けるポートは環境変数 MDMARK_PORT で決め、無ければ 8782 にする（設定）。
| コード | 意味 |
|---|---|
0 |
Ctrl+C（SIGINT）か SIGTERM を受けて、待ち受けを閉じた |
1 |
ポートを別のプロセスが使っている。標準エラーに、ポートの番号と、~/.claude/settings.json の env と serve を起動する環境の両方に同じ MDMARK_PORT を設定すれば別のポートで動かせること、serve が既に起動しているならそのまま使えることを出す |
1 |
MDMARK_PORT が 1〜65535 の整数でない。標準エラーに、受け取った値と、1〜65535 の整数を設定することを出す |