mdmark

設定

設定のキーと既定の一覧

mdmark.config.yaml に書くキーの一覧。 mdmark はブラウザで YAML を読まない。 使う側のサーバーが mdmark.config.yaml を読んだオブジェクトを、mount と render の opts.config に渡す（文書を描く）。 どのキーも省ける。省いたキーには既定を当てる。 設定の形の正は、リポジトリの schemas/mdmark.config.schema.json（JSON Schema）に置く。 この一覧のキーは全て Schema が検め、この一覧にないキーを書いても、mdmark は読まず、Schema も拒まない。 CLI は mdmark.config.yaml を自分で読んで、書き出しに使う（CLI）。 theme・extensions・build・check は CLI だけが読み、mount と render は読まない。 version は mdmark upgrade だけが読む。

一覧

名前	キー	説明
機能の既定	features	機能ごとのオン・オフの既定
印刷の機能	features.print	印刷の前に閉じた折り畳みとタブ・閉じた節・行の詳細を開き、印刷の後に戻す
記法の機能	features.table ほか	記法ごとのオン・オフ
用語の機能	features.glossary	用語のツールチップと用語集の表のオン・オフ
被参照の機能	features.backlinks	被参照の一覧と文書の別名のオン・オフ
コメントの機能	features.comments	本文の選んだ箇所へのコメントのオン・オフ（既定はオフ）
外部ライブラリの対応表	libraries	印の名前から外部ライブラリのモジュールの URL を引く
色分けのライブラリの読み込み先	syntax.url	コードブロックの色分けに使うライブラリ（highlight.js）の es/ フォルダの URL
ツールチップを出す場所	tooltips.placement	用語・図・ヒントのツールチップを、持ち主の上と下のどちらに先に出すか
索引の場所	index	索引の YAML のパス
使う側の CSS	theme	CLI が書き出す HTML に埋める使う側の CSS のパス
拡張のモジュール	extensions	CLI が書き出す HTML に埋め、描く前に登録する拡張のモジュールのパスの並び
まとめる設定	build ほか	mdmark build がまとめる文書と書き出す先
点検から外す名前	check.ignore	mdmark check が知らない印として知らせない HTML コメントの名前の並び
手元の版	version	設定・索引・文書が合わせてある mdmark の版
MCP サーバーのポート	環境変数 MDMARK_PORT	mdmark serve が待ち受けるポート。設定ファイルには書かない

機能の既定

機能ごとのオン・オフの既定を決める。 文書の <!-- features: +機能 -機能 --> が、その文書だけ上書きする（優先順は 文書を描く仕組み）。

項目	内容
型	キーが機能名、値が真偽値のオブジェクト
既定	comments を除く全ての機能が true
許す値	値は true か false。知らない機能名と、真偽値でない値は無視する

features:
  print: false

印刷の機能

印刷の前に閉じた折り畳みと、タブ・閉じた節・行の詳細を開き、印刷の後に印刷の前の開閉へ戻す。 見え方は 印刷する。

項目	内容
型	真偽値
既定	true

記法の機能

記法ごとにオン・オフを決める。 オフにした記法は、書いた Markdown を普通の Markdown として描く。 書き方は 記法。

項目	内容
型	真偽値
既定	true

features:
  table: false
  callout: false

キー	記法	オフのときの描き方
features.table	表	表の印を取り除いて、普通の表を描く
features.callout	注意書き	引用のまま描く
features.tabs	タブ	範囲の中身をそのまま描く
features.steps	ステップ	番号付きリストのまま描く
features.tree	ファイルツリー	コードブロックのまま描く
features.badge	バッジ	行内のコードのまま描く
features.code	コードブロックの飾り	コードブロックの印を取り除き、題・行番号・行の強調を付けない。コードの行の印は書いた文字のまま描く
features.syntax	コードブロックの飾り	色分けのライブラリを読まず、コードブロックを色分けしない。題・行番号・行の強調・コードの行の印は変わらない
features.toc	目次	印を取り除く
features.anchors	見出しのアンカー	見出しの ID へのリンクを付けない。見出しの ID は付ける
features.sections	節の開閉	節を囲まず、section の印を取り除く
features.row-details	行の詳細	範囲の中身を、表の後の本文として描く
features.figures	図と表の番号	印を取り除き、リンクの文字を変えない
features.diagrams	図の部品	印を取り除き、定義を json のコードブロックのまま描く
features.html	埋め込んだ HTML	印を取り除き、html のコードブロックをコードのまま描く
features.hints	ヒント	data-hint・箱の hint と io・線の tip のツールチップの中身と印を出さない。線のラベルと箱の名前は出す
features.views	ビュー	印を取り除き、範囲の表を普通の表として描く。ビューの部品のモジュールは読まない

用語の機能

索引の用語と用語集の表の用語に、破線の下線と意味のツールチップを付ける。 書き方は 索引と用語集を書く。 オフのときは、本文の用語に下線を付けず、用語集の表を普通の表として描く（表の印は取り除き、書き方の警告も出さない）。

項目	内容
型	真偽値
既定	true

被参照の機能

文書の末尾に被参照の一覧を置き、索引の文書の aliases に一致した本文の語にも下線とツールチップの「関連文書」を付ける。 オフのときは、末尾の一覧を出さず、文書の別名にだけ一致する語に下線を付けず、ツールチップから「関連文書」の区分を外す。 参照の表を作るときも、backlinks がオフの文書は参照元にも参照先にもならない（参照の表を作る）。

項目	内容
型	真偽値
既定	true

features:
  glossary: false
  backlinks: false

コメントの機能

読む人が本文の選んだ箇所にコメントを付けられるようにする。 使う側が mount にコメントの読み書きの関数（opts.commentStore）と opts.docId を渡したときだけ効く（文書を描く）。 オフのときは、文字を選んでもコメントのボタンを出さず、読み書きの関数の load も呼ばない。 オンで読み書きの関数を渡さないときは、ボタンを出さず、console.error に読み書きの関数が要ることを 1 回だけ出す。 書き方は ビューとコメントを使う。

項目	内容
型	真偽値
既定	false
既定がオフの理由	コメントは使う側の保存先が要り、使わない文書で文字を選ぶたびにボタンを出さないため

features:
  comments: true

外部ライブラリの対応表

印の名前から、外部ライブラリのモジュールの URL を引く。 mdmark が持つ既定の対応表に重ね、同じ名前は URL を上書きし、対応表に無い名前は足す。 この版は既定の対応表を持たない。 足した名前の印は図の印として扱い、読めないときの知らせの枠の題は この図を表示できません になる。

項目	内容
型	キーが印の名前、値が URL の文字列のオブジェクト
既定	{}
許す値	キーは英小文字で始まり、英小文字・数字・- だけを持つ。値は文字列の URL で、相対 URL はページの document.baseURI を基準に解決する。書式に合わないキーと、文字列でない値は無視する

libraries:
  my-chart: /assets/my-chart.js

モジュールは、draw(slot, args) を名前付きで export する。 slot は印の場所の要素、args は印の引数を空白で区切った文字列の配列で、draw は同期でも Promise を返す非同期でもよい。 文書に <!-- my-chart: a b --> と書くと、slot と ["a", "b"] を渡して draw を呼ぶ。

色分けのライブラリの読み込み先

コードブロックの色分けに使うライブラリ（highlight.js）の es/ フォルダの URL を書く。 本体を {url}core.min.js、言語を {url}languages/{言語}.min.js から読む。 libraries とは別のキーで、文書に印を書かせない。 mount が読み、render は読まない。 CLI は mdmark.config.yaml のあるフォルダを基準に相対パスを解決し、書き出す HTML に使う言語の分だけを埋める（文書を書き出す）。

項目	内容
型	文字列
既定	https://cdn.jsdelivr.net/npm/@highlightjs/cdn-assets@11.12.0/es/
許す値	末尾が / の URL かパス。mount は相対パスをページの document.baseURI を基準に解決し、文字列でない値を無視して既定を当てる。CLI は文字列でない値を設定ファイルの誤りにする

syntax:
  url: /vendor/highlightjs/es/

差し替える先には、@highlightjs/cdn-assets の es/ フォルダをそのまま置く。 色分けのオン・オフは features.syntax（記法の機能）で決める。

ツールチップを出す場所

用語・図・ヒントのツールチップを、持ち主（下線の語・線のラベル・箱やヒントの印）の上と下のどちらに先に出すかを決める。 top は上に出し、上に収まらないときだけ下に出す。 bottom は下に出し、下に収まらず上に収まるときだけ上に出す。 mount が読み、render は読まない。

項目	内容
型	top か bottom の文字列
既定	top
許す値	top・bottom。mount は他の値を無視して top にし、CLI は他の値を設定ファイルの誤りにする

tooltips:
  placement: bottom

索引の場所

索引の YAML のパスを書く。 パスは、mdmark.config.yaml のあるフォルダからの相対パスで書く。 索引の文書の path は、この索引のファイルのあるフォルダからの相対パスで書く（索引）。 mdmark はブラウザでファイルを読まず、mount と render もこのキーを読まない。 使う側のサーバーがこのパスの YAML を読み、読んだオブジェクトと描く文書の id を opts.index・opts.docId に渡す（文書を描く）。 索引の形は 索引。 CLI はこのパスの索引と、索引の文書を読み、参照の表を作って書き出しに埋める。

項目	内容
型	文字列
既定	なし。省くと索引を渡さない文書と同じに描く

index: docs/index.yaml

使う側の CSS

CLI が書き出す HTML に、配布物の CSS の後で埋める使う側の CSS のパスを書く。 パスは、mdmark.config.yaml のあるフォルダからの相対パスで書く。 手順は 文書を書き出す。

項目	内容
型	文字列
既定	なし。使う側の CSS を埋めない
許す値	ファイルのパス。読めないときは書き出しを止めず、警告に出す

theme: theme.css

拡張のモジュール

CLI が書き出す HTML に束ねて埋め、描く前に registerExtension で登録する拡張のモジュールのパスを並べる。 各モジュールは、registerExtension に渡す拡張を既定の export にする（拡張の形は 拡張を登録する）。 mdmark check はモジュールを Node で読み込んで directive を取るため、読み込みの時点でブラウザの API（HTMLElement・window など）を使わず、使うのは load の中だけにする。 パスは、mdmark.config.yaml のあるフォルダからの相対パスで書く。

項目	内容
型	文字列の配列
既定	[]。拡張を埋めず、拡張の印は知らない印として取り除かれる
許す値	TypeScript か JavaScript のファイルのパス。読めない・束ねられないものは書き出しを止めず、警告に出す

extensions:
  - extensions/example.ts

まとめる設定

mdmark build が 1 枚の HTML にまとめる文書と、書き出す先を決める。 パスと glob は、mdmark.config.yaml のあるフォルダからの相対パスで書く。 手順は 文書を1枚にまとめる。

項目	内容
型	オブジェクト
既定	なし。mdmark build は、build が無いことを出して終了コード 1 で終わる

build:
  include: ["**/*.md"]
  exclude: ["下書き/**"]
  glossary: ["用語集.md"]
  entry: README.md
  out: dist/docs.html

キー	型	必須	既定	説明
build.include	文字列の配列	必須	なし	まとめる Markdown の glob。**・*・? を使え、当たるのは拡張子 .md のファイルだけ。1 つ以上書く。文書は glob の並びで並べ、同じ glob の中はパスの順に並べ、重なりは最初の 1 つだけを残す
build.exclude	文字列の配列	任意	[]	include に当たった文書から外す glob。書き方は include と同じ
build.glossary	文字列の配列	任意	[]	用語集の表（glossary の印）を持つ文書のパス。表の用語を、まとめた全ての文書で効かせる。索引が無いときも効く。まとめる文書に当たらないパスは、mdmark check で schema のずれにし、mdmark build では飛ばして警告に出す
build.entry	文字列	任意	include で最初に当たった文書	開いたとき、URL の # が文書を指していないときに出す文書のパス。まとめる文書に当たらないときは、mdmark check で schema のずれにし、mdmark build では既定を当てて警告に出す
build.out	文字列	必須	なし	まとめた HTML を書くパス。拡張子 .html で書く。既にあれば上書きし、親のフォルダが無ければ作る

build.include と build.out が無いと、mdmark build は終了コード 1 で終わり、mdmark check は schema のずれにする。

点検から外す名前

mdmark check が文書の本文の知らない印として知らせない、印と同じ書き方の HTML コメントの名前を並べる。 <!-- prettier-ignore -->・<!-- markdownlint-disable --> のような他のツールへの指示を書いた文書で使う。

項目	内容
型	文字列の配列
既定	[]。印に当たらない名前を全て知らない印として知らせる
許す値	英小文字で始まり、英小文字・数字・- が続く名前。合わないと mdmark check は schema のずれにする

check:
  ignore:
    - prettier-ignore
    - markdownlint-disable

手元の版

この設定・索引・文書が合わせてある mdmark の版を書く。 mdmark init が呼んだ CLI の版を書き、mdmark upgrade が移行の手順を当てて点検が通った後に、呼んだ CLI の版へ書き換える。 手順は 版を上げる。 mount・render・export・build・check は、値で振る舞いを変えない。

項目	内容
型	文字列
既定	なし。mdmark upgrade が手元の版を聞く（v0.3.0 までの init が置いた設定）
許す値	v{MAJOR}.{MINOR}.{PATCH} の形。合わないと mdmark check は schema のずれにする

version: v0.4.0

MCP サーバーのポート

mdmark serve が 127.0.0.1 で待ち受けるポートを、環境変数 MDMARK_PORT で決める。 設定ファイルには書かない。 プラグインの .mcp.json の接続先 http://127.0.0.1:${MDMARK_PORT:-8782}/mcp も同じ環境変数で決まるため、変えるときは ~/.claude/settings.json の env と mdmark serve を起動する環境の両方に同じ値を設定する。 手順は MCPサーバーを起動する。

項目	内容
型	整数（環境変数の値は文字列）
既定	8782
許す値	1〜65535 の整数。範囲外・整数でない値だと、mdmark serve は待ち受けずに終了コード 1 で終わる
反映	mdmark serve を起動し直し、Claude Code のセッションを開き直す

{
  "env": {
    "MDMARK_PORT": "18782"
  }
}