mdmark

用語集

印・記法・テーマ・機能・知らせの枠・書き方の警告・行の強調・コードの行の印・索引・被参照・本文の一致・参照先・点検・やめた言い方・タグの語彙・主題のタグ・関係の種類・逆向きの関連・書き出し・まとめた HTML・雛形・移行の手順・手元の版・壊す手順・図の部品・埋め込んだ HTML・ヒント・差分・リビジョン・取り出し元・ビュー・ボード表示・コメント・共通の定義・固有の定義・使い方集・プラグイン・MCP のツール・常駐サーバー・VS Code 拡張機能・プレビュー・描けない理由・元の行番号の用語の意味

mdmark の公開ドキュメントで使う用語の一覧。

一覧

用語 意味 詳細
印 文書に書く <!-- 名前: 引数 --> の形の HTML コメント（引数の無い印は <!-- 名前 -->）。名前は英小文字で始まり、英小文字・数字・- だけを持ち、引数は空白で区切る。コードブロックと行内のコードの中は印として扱わない。描いた本文には残らない 文書を描く仕組み
印の場所 外部ライブラリの印を置き換えた要素。外部ライブラリのモジュールが描く先になる 外部ライブラリの対応表
対応表 印の名前から、外部ライブラリのモジュールの URL を引く表。mdmark が持つ既定に、設定の libraries を重ねる 外部ライブラリの対応表
機能 mdmark の働きのうち、オン・オフを決められるもの。設定の features が既定を決め、文書の印がその文書だけ上書きする 機能をオン・オフする
テーマ 描いた文書の見た目。--mdmark- で始まる CSS 変数と、@layer mdmark に入れた mdmark の CSS で決まる テーマを上書きする
層 mdmark の CSS を入れる @layer mdmark。使う側が層の外に書いた CSS は、詳細度によらず層の中の mdmark の CSS に勝つ 文書を描く仕組み
読み込み中の枠 外部ライブラリを読み込んでいる間、印の場所に出す破線の枠。図を読み込んでいます と出し、図の高さを先に取る 文書を描く仕組み
知らせの枠 外部ライブラリや拡張のモジュールを読めない印の場所に出す枠。題は この図を表示できません（図でない印は この箇所を表示できません）で、本文に読めなかった印の名前と直し方を書く 文書を描く
範囲の印 <!-- 名前: 引数 --> 〜 <!-- /名前 --> で本文を囲む印。閉じの印は <!-- /名前 -->。印に対応しない表示では印が見えず、囲んだ Markdown がそのまま読める 記法
記法 印や書き方で、表・注意書き・タブなどの表示を付けるもの。記法ごとに機能としてオン・オフできる 記法
表の種類 表の印に書く data・plain。種類ごとに並べ替え・ピン止め・絞り込みの機能が決まり、囲まない表は既定の種類になる 表
集計の行 +total と total=列名:計算 を書いた表の末尾に置く行。表示している行を sum（合計）・avg（平均）・count（空でないセルの数）で集計し、絞り込みに合わせて計算し直す。題は 合計・平均・個数 表
行へのリンク +rowlink を書いた表の各行の先頭のセルに置く、その行を指す #ID のリンク。#ID は先頭の列の文字から見出しのアンカーと同じ規則で作る。URL の #ID が行を指すと、その行へ移って強調する 表
注意書き 1 行目が [!NOTE] などの引用を、種類ごとの題・色・アイコンを持つ枠にしたもの。末尾に - を付けると閉じた折り畳みになる 注意書き
タブ <!-- tabs --> の範囲を、見出しの文字をタブ名にして切り替えて見せるもの タブ
タブの組 タブの印の group=名前 で付ける名前。同じページで同じ組のタブ群は、選んだタブ名を揃え、読む人が選んだタブ名を localStorage に残して、次に描くときもそのタブを選ぶ タブ
ステップ 番号付きリストを、番号と項目をつなぐ線を持つ手順にしたもの ステップ
ファイルツリー 言語 tree のコードブロックの罫線を、フォルダとファイルの入れ子のツリーにしたもの ファイルツリー
バッジ 頭に badge\: を付けた行内のコードを、頭を外した文言の札にしたもの バッジ
行の強調 コードブロックの直前の印の highlight=行,… か、行末の [!code highlight] で、コードブロックの行に強調の色と左端の線を付けること。色以外でも見分けられる コードブロックの飾り
色分け コードブロックの情報文字列の言語に応じて、キーワード・文字列・数値・型・名前・コメントの 6 種類を色で分けること（シンタックスハイライト）。typescript・javascript・json・yaml・python・bash・html・css・markdown・sql の 10 言語を、mount が描いた後に付ける。色分けのライブラリは配布物に含めず、色分けする言語のコードブロックがある文書でだけ、バージョンを固定した URL から読む。設定の features.syntax か文書の印でオン・オフする コードブロックの飾り
コードの行の印 コードブロックの行末の行コメントに書く [!code ++]（足した行）・[!code --]（消した行）・[!code highlight]（強調）。行を色と行頭の +・- で分け、印と、印だけを持つ行コメントの頭は画面に出さない。[ の後ろに \ を入れると打ち消し、\ を外した文字のまま出す コードブロックの飾り
節の開閉 見出し（h2〜h4）の節を、見出しから開閉すること。見出しの直後の section の印で、閉じた状態で始められる 節の開閉
行の詳細 表の行の下に開閉して出す詳細。表の直後の row-detail の範囲に書く 行の詳細
図表の番号 fig の印の直後の図と表に付ける、種類ごとの通し番号（図 1・表 1） 図と表の番号
拡張 使う側が registerExtension で足す印。文書に印があるときだけ、モジュールを読んで印の場所に描かせる 拡張を登録する
書き方の警告 記法の印や拡張の引数に読めない指定がある箇所に出す、題 書き方の警告 の枠。読めた指定で本文を描き、読めない指定と直し方を書く 書き方の警告
索引 使う側が書く YAML のファイル。文書（docs）と用語（terms）、任意でタグの語彙（tags）を並べる。使う側が読んだオブジェクトを mount・render に渡す 索引
用語集の表 glossary の印で囲んだ表。用語・意味・別名の列から用語を入れる。表の中の語には下線を付けない 用語集の表
用語のツールチップ 本文に出た用語の語・別名に破線の下線を引き、ポインターを乗せるかフォーカスすると出す枠。見出し「用語」に意味を、見出し「関連文書」に文書の別名に一致した文書を出す。やめた言い方には破線でなく波線のマーカーを引き、見出し「代わりの用語」を出す 索引と用語集を書く
文書の別名 索引の文書の aliases。本文に出た語に用語と同じ規則で下線を付け、ツールチップの「関連文書」に一致した文書を出す 索引
関連文書 ツールチップの区分（語に文書の別名が一致した文書）と、文書の末尾に置く一覧（その文書を参照している文書）の題 索引と被参照
被参照 ある文書を参照している文書。保存せず、索引の related・本文の文書間のリンク・文書の別名の出現から、描くときに算出する 索引と被参照
参照の表 文書ごとの被参照と、各文書の用語集の表の用語をまとめた表。collectReferences が返し、mount・render の opts.references に渡す 参照の表を作る
本文の一致 本文に出た用語・文書の別名の 1 回の出現。collectMatches が、参照先・一致した文字列・本文の位置（行と、行の中の始まりと終わり）の組で、文書ごとに返す。照合の規則は描いた文書の下線と同じ 本文の参照を取り出す
参照先 本文の一致が指す、索引の用語・用語集の表の用語・文書。種類・id・タイトル・短い説明で表し、collectMatches が渡した全ての文書の分を重なりを除いてまとめて返す 本文の参照を取り出す
点検 索引と文書のずれを見つける処理（checkIndex）。ずれは、ファイル・場所・種類・内容の一覧で返る 索引を点検する
やめた言い方 索引の用語の avoid か、用語集の表の avoid= の列に並べる、使わないことにした言い方。索引の文書の本文に出ると、点検が avoided_term のずれで知らせる。索引の用語の avoid と用語集の表の avoid= の列のやめた言い方は、描いた文書の本文に出ると波線のマーカーを付け、見出し「代わりの用語」のツールチップに代わりの用語の語と意味を出す。collectMatches は、本文に出たやめた言い方を位置と代わりの用語つきで avoided に返す 索引と用語集を書く
タグの語彙 索引の最上位の tags に並べる、タグ 1 つごとの名前・グループ・説明（含める / 含めない / 例）・別名・振り替え先。文書のタグと find_docs・list_tags に渡すタグは、語彙の名前と別名に突き合わせる。語彙を記載した索引では、語彙に無いタグ・やめたタグ・語彙のずれを点検が知らせ、list_tags が語彙を付いている文書の数つきで返す 索引
主題のタグ 文書のタグのうち、その文書の主題を表す main: true のタグ。find_docs は、絞り込みのタグが主題のタグに当たる文書を上に並べ、返すタグに主題かどうかを添える 文書を探す
関係の種類 索引の related の要素の type。requires（前提）・references（参照）・replaces（置き換え）・part_of（一部）・change_together（一緒に直す）のどれか。同じ要素の when に、いつ読むかを 1 文で記載する 索引
逆向きの関連 関連を記載した文書の相手から見た関係。関連は片側だけに記載し、逆向きは保存せず、find_docs の related_to が向き（outgoing / incoming）と逆向きの名前（required_by・referenced_by・replaced_by・has_part）つきで出す。change_together だけは両側に記載する 文書を探す
書き出し CLI の mdmark export と mdmark build が、Markdown を、配布物・使う側の CSS・外部ライブラリのモジュール・拡張・画像を埋めた 1 枚の HTML にすること。開いてから描き終えるまで、ページ自身と blob:・data: のほかへ要求しない CLI
まとめた HTML mdmark build が書き出す、複数の文書を埋めた 1 枚の HTML。文書の一覧と開いている文書を並べ、URL の #/{文書のパス} で文書を行き来する 文書を1枚にまとめる
文書の一覧 まとめた HTML の、まとめた文書へのリンクを並べた一覧。フォルダの無い文書を先に置き、続けてフォルダごとの見出しでまとめ、開いている文書の行を背景で示す 文書を1枚にまとめる
雛形 mdmark init が置く、設定・theme.css・索引・拡張の例のファイル 雛形を置く
移行の手順 版ごとに mdmark の開発者が書く、設定・索引・文書を新しい版に合わせる手順。mdmark upgrade が、手元の版より新しく目標の版以下の版の分を版の順に当てる。キーの名前を変える・キーを足す・値を読み替える・文書の印を書き換える・スクリプトで当てる、の 5 種類があり、どれも当て直しても結果が変わらない 版を上げる仕組み
手元の版 設定・索引・文書が合わせてある mdmark の版。設定の version に v{MAJOR}.{MINOR}.{PATCH} の形で書く。mdmark upgrade が、呼んだ CLI の版（目標の版）まで移行の手順を当てた後に、目標の版へ書き換える 手元の版
壊す手順 当てると値が失われる移行の手順。mdmark upgrade --plan が（壊す手順）と示し、--yes が無いとき当てる前に確かめる 版を上げる
図の部品 文書に書いた部品の定義から描く、フロー図・シーケンス図・グラフ・操作できる部品。flow・sequence・chart・param の範囲の印に json のコードブロックを置く 図の部品
部品の定義 図の部品や拡張の印の範囲に置く、描く中身を書いた JSON。式もスクリプトも書かず、definition として部品に渡る 図を描く
埋め込んだ HTML <!-- html --> の範囲の html のコードブロックに書き、コードではなくその場の HTML として描く HTML。script 要素とイベントの属性は落とし、動くのは mdmark の部品だけ 埋め込んだ HTML
チャート 埋め込んだ HTML の中の custom element（<mdmark-chart> など）に部品の定義を書いて描く図。グラフは折れ線・棒・円・散布図を描ける コードブロックのHTMLを描く
ヒント data-hint・図の箱の hint と io・線の tip を、ホバーとフォーカスで開くツールチップで出す文。設定の features.hints でまとめて外せる ヒント
差分 文書の 2 つのリビジョンの Markdown のソースを行で比べ、削除した行を赤と行頭の -、追加した行を緑と行頭の +、対の行で変わった語を濃い色で出す表示。mount に取り出し元を渡すと、題の後ろの「変更を見る」のボタンで開く 差分を表示する仕組み
リビジョン 文書の変更の 1 回分。取り出し元が返す id・at・label・author を持ち、差分で比べる前と後に選ぶ。mdmark の版とは別のもの 文書を描く
取り出し元 使う側が書く DiffSource。リビジョンの一覧を返す revisions と、リビジョンごとの本文を返す content を持ち、mount の opts.diffSource に渡す。Git や YAML の読み方は使う側が持つ 差分を表示する
ビュー view の印の範囲の最初の表を項目にして、ボード表示と表形式のビューを切り替えて見せるもの。使う側の JavaScript からは mountView で描く ビュー
ボード表示 ビューの表示の 1 つ。group= の列の値ごとの列に項目を並べ、列の見出しに値のアイコンと項目の数を出す ビュー
表形式のビュー ビューの表示の 1 つ。範囲の表を使い、並べ替えと、filter= で指定した列の絞り込みを付ける。絞り込みはボード表示に当てない ビュー
コメント 読む人が本文の選んだ箇所に付ける意見。選んだ文字・その前後の文字・本文の組で、使う側の保存先に残る。機能 comments で付けられるようにする ビューとコメントを使う
コメントの印 コメントが付いた本文の文字を包む印。本文の文字は変えず、押すと付いたコメントの吹き出しを開く ビューとコメントを使う
コメントの読み書きの関数 使う側が書く MdmarkCommentStore。コメントを読み込む load と保存する save を持ち、mount の opts.commentStore と mountComments の opts.store に渡す。mdmark はコメントを保存しない 文書を描く
箇所が見つからないコメント 本文が書き換わり、コメントを付けた文字が見つからないコメント。文書の末尾の 箇所が見つからないコメント の一覧に、選んだ文字と本文を並べる ビューとコメントを使う
共通の定義 mdmark が持つ図の部品と、色・文字・ライト / ダークの CSS 変数。どの文書でも使える 共通の定義と固有の定義
固有の定義 使う側が registerExtension と theme.css で足す部品と CSS。足した設定ファイルの単位の文書にだけ当たる 共通の定義と固有の定義
VS Code 拡張機能 VS Code で Markdown を mdmark で描いたプレビューを出し、HTML への書き出しと PDF への印刷をするための拡張機能。mdmark の配布物は同梱せず、jsDelivr の版付きの URL から読む。mdmark 本体とは別のタグ vscode-v{バージョン} で配る VS Code 拡張機能
プレビュー VS Code 拡張機能が Webview のパネルに出す、開いている Markdown を mdmark で描いた文書。打つたびに描き直し、エディタとスクロールを合わせ、VS Code のテーマの明暗に合わせる プレビューを開く
描けない理由 プレビューが配布物を読めないとき、文書の代わりに出す理由と「リロード」のボタン。オフライン・指定したバージョンが無い・バージョンを決められない、の 3 種類がある プレビューを開く
元の行番号 本文のブロックの開始の要素に付く data-source-line。ブロックが Markdown で始まる行の番号（0 始まり）で、エディタとプレビューのスクロールを合わせる手がかりになる 文書を HTML 文字列にする
line jump 図の横の線が縦の線と交わる点に入れる飛び越えの弧 構成図の決まり
凡例 図の下に並べる、定義に出る箱の種類・線の種類・系列と、図にある枠・層・交差・印・下線の意味の一覧 構成図の決まり
使い方集 Claude Code に渡す mdmark の使い方。索引（名前・読むとき・概要・本文のページ）と、索引の行が指す docs/ のページの本文からなる。索引はセッションの開始で渡し、本文は read_guide に名前を渡して読む Claude Code に使い方を渡す仕組み
プラグイン mdmark のリポジトリの plugin/ にある Claude Code のプラグイン。入れると、SessionStart のフックが使い方集の索引を渡し、MCP サーバーが常駐サーバーへつながる プラグインを入れる
MCP のツール プラグインの MCP サーバーが出し、Claude Code から呼ぶ read_guide・export_html・build_site・check・find_docs・list_tags・update_index MCP
常駐サーバー 文書を書く人が mdmark serve で起動し、127.0.0.1 の /mcp で待ち受ける MCP サーバー。ポートは既定 8782 で、環境変数 MDMARK_PORT で変える。並行して開いたセッションが同じプロセスを共有し、起動していないと Claude Code の MCP サーバーだけが接続に失敗する MCPサーバーを起動する