mdmark

索引

索引のキー・型・必須・既定と、点検が返すずれの種類の一覧

使う側が文書のメタデータと用語を書く YAML のファイルの形。 場所は設定の index で決める（索引の場所）。 mdmark はブラウザでファイルを読まない。 使う側のサーバーが読んだオブジェクトを、mount・render・collectReferences・checkIndex に渡す（API）。 形は、リポジトリの schemas/mdmark.index.schema.json（JSON Schema draft 2020-12）で縛る。 書き方の手順は 索引と用語集を書く。

一覧

名前	キー	説明
最上位のキー	schema・docs・terms・tags	索引の版と、文書・用語・タグの語彙の並び
文書	docs[]	索引に載せる文書 1 つのメタデータ
用語	terms[]	索引に載せる用語 1 つ。本文に出たら意味のツールチップを付ける
タグの語彙	tags[]	索引に載せるタグ 1 つと、その説明・別名・振り替え先
点検が返すずれ	kind	checkIndex が返すずれの種類

最上位のキー

ここに挙げたキー以外は書けない。

キー	型	必須	説明
schema	整数	必須	索引の版。今は 1
docs	文書の並び	必須	索引に載せる文書
terms	用語の並び	任意	索引に載せる用語
tags	タグの語彙の並び	任意	索引に載せるタグの語彙

schema: 1
docs:
  - id: arch
    path: 設計/arch.md
    title: アーキテクチャ
    description: 全体の構成と依存の向き
    aliases: [構成図]
    tags: [設計, { name: topic:mcp, main: true }]
    related:
      - to: api
        type: requires
        when: 公開関数の仕様を確かめるとき
  - id: api
    path: api.md
    title: API
terms:
  - id: workspace
    term: ワークスペース
    aliases: [WS]
    meaning: 話し合いの記録を置くフォルダ
    avoid: [作業場]
tags:
  - name: topic:mcp
    group: topic
    description: "含める: MCP のツールの作り方。含めない: Claude Code の設定。例: find_docs の引数"
    aliases: [MCP]
  - name: 設計
    group: kind

文書

索引に載せた文書 1 つのメタデータ。

キー	型	必須	既定	説明
id	文字列	必須	なし	文書の ID。docs の中で一意。空にできない
path	文字列	必須	なし	文書のパス。索引のファイルのあるフォルダからの相対パスで、区切りは /。docs の中で一意。空にできない
title	文字列	必須	なし	文書の題。関連文書のリンクの文字に出す。空にできない
description	文字列	任意	なし	1 文の概要。ツールチップの「関連文書」に出す
aliases	文字列の並び	任意	[]	本文での呼び名。本文に出たら、その語のツールチップの「関連文書」にこの文書を出し、被参照にも数える。要素は空にできない
tags	タグの並び	任意	[]	タグ。描くことには使わず、MCP の find_docs の絞り込みと並びに使う。要素はタグの名前の文字列か、name（必須・空にできない文字列）と main（主題のタグか。任意・既定 false）を持つオブジェクト。文字列の要素は main: false と同じ。タグの語彙（最上位の tags）を記載した索引では、点検が語彙とのずれを知らせる（タグのずれ）
related	関連の並び	任意	[]	この文書から他の文書への関連。要素は関連のオブジェクトか、関連する文書の id の文字列（関連の要素）。件数の上限は置かない。to（文字列の要素はその文字列）をこの文書からその文書への参照として数える。索引に無い id は点検が知らせる

関連の要素

docs[].related のオブジェクトの要素のキー。 ここに挙げたキー以外は書けない。

キー	型	必須	説明
to	文字列	必須	相手の文書の id。空にできない
type	文字列	必須	関係の種類。requires・references・replaces・part_of・change_together のどれか
when	文字列	必須	いつ読むかの 1 文。空にできない
paths	文字列の並び	任意	関連が当たるファイルの glob の並び。要素は空にできない

関係の種類は次のとおり。 逆向きの名前は、MCP の find_docs の related_to が、相手から見た関係として返す。

type	意味	逆向きの名前
requires	相手を先に読まないと分からない	required_by
references	相手を必要なときに引く	referenced_by
replaces	相手を置き換えた	replaced_by
part_of	相手の一部をなす	has_part
change_together	片方を直したらもう片方も直す	change_together

関連は片側だけに記載し、逆向きは find_docs が出す。 change_together だけは、両側に記載する。 片側にしか記載していない change_together は、点検が one_sided_change_together で知らせる。

文字列の要素も読める。 type と when を持たない関連として扱い、点検が untyped_related でオブジェクトへの書き換えを求める。

用語

索引に載せた用語 1 つ。本文に出たら意味のツールチップを付ける。

キー	型	必須	既定	説明
id	文字列	必須	なし	用語の ID。terms の中で一意。節ごとに最初の 1 回だけ下線を付ける単位。空にできない
term	文字列	必須	なし	用語の語。空にできない
aliases	文字列の並び	任意	[]	別名。本文に出たら、用語と同じツールチップを出す。要素は空にできない
meaning	文字列	必須	なし	意味。ツールチップの「用語」に出す。空にできない
avoid	文字列の並び	任意	[]	やめた言い方。索引の文書の本文に出たら、点検が avoided_term で知らせる。描いた文書では、本文に出たやめた言い方に波線のマーカーを付け、見出し「代わりの用語」に用語の語と意味を出したツールチップを出す。要素は空にできない

題・意味・概要は Markdown として解析せず、文字として出す。

タグの語彙

索引に載せたタグ 1 つと、その説明・別名・振り替え先。 語彙は索引に 1 つだけ置き、同じ name のタグをグループごとに別に定義しない。 文書の tags と、MCP の find_docs・list_tags に渡すタグは、この name と aliases に突き合わせる。

キー	型	必須	既定	説明
name	文字列	必須	なし	タグの名前。語彙の中で一意にする。空にできない。重なっても Schema は拒まず、点検が duplicate_tag で知らせる
group	文字列	任意	なし	タグのグループ（topic・kind・scope・tool など）。空にできない
description	文字列	任意	なし	タグを付ける文書の「含める / 含めない / 例」。MCP の list_tags が返す
aliases	文字列の並び	任意	[]	タグの別名。文書の tags と find_docs に渡した別名は、このタグの name として扱う。要素は空にできない
deprecated	文字列	任意	なし	やめたタグのとき、代わりに使うタグの name。書いたタグはやめたタグになる。空にできない

説明は Markdown として解析せず、文字として出す。

点検が返すずれ

checkIndex が返すずれ 1 件の kind。 一覧の並びは、この表の順。

kind	意味	where
schema	索引が Schema に合わない。必須のキーの欠け・型の違い・docs[].id・docs[].path・terms[].id の重なり・知らないキーを、合わないところごとに返す	合わないキーのパス（docs[1].path）。最上位は schema
missing_doc	索引にあって、文書が見つからない	索引の docs[].path
orphan_doc	文書があって、索引に無い	空文字
broken_ref	related の id（オブジェクトの要素は to）が索引に無い	索引の docs[].related[]（オブジェクトの要素は docs[].related[].to）
untyped_related	related の要素が type と when を持たない文字列。to・type・when を持つオブジェクトへの書き換えを求める。文字列の要素ごとに 1 件	索引の docs[].related[]
one_sided_change_together	change_together の相手が索引にあるのに、相手の related に自分を to とする change_together が無い。片側だけに記載した要素ごとに 1 件	索引の docs[].related[]
related_link_overlap	change_together でない related の相手を、自分の本文でもリンクしている。文字列の要素を含む。要素ごとに 1 件	索引の docs[].related[]
missed_change_together	change_together の組のうち、片方の文書だけが比べる基準から変わっている。組ごとに 1 件。基準を渡したときだけ返す	空文字
duplicate_term	用語の語か別名が、NFKC・英字の小文字化・前後の空白の除去で正規化した後に重なっている。索引の terms どうし・索引の terms と用語集の表・用語集の表どうしで、重なり 1 組ごとに 1 件	組の後の側の場所（下記）
avoided_term	索引の文書の本文に、用語のやめた言い方（索引の用語の avoid と、用語集の表の avoid= の列）が出ている。出た行とやめた言い方の組ごとに 1 件	やめた言い方が出た文書の中の行（8 行目）
duplicate_tag	タグの語彙の name が重なっている。2 つ目以降に出た同じ name ごとに 1 件	語彙の tags[2].name
tag_alias_conflict	タグの語彙の aliases が、別のタグの name か aliases と重なっている。別名ごとに 1 件	語彙の tags[1].aliases[0]
broken_tag_replacement	タグの語彙の deprecated の振り替え先が、語彙のどの name にも当たらない	語彙の tags[4].deprecated
unregistered_tag	文書のタグが、語彙の name にも aliases にも当たらない。語彙に足すか、近いタグに直す候補	索引の docs[0].tags[1]
deprecated_tag	文書のタグが、やめたタグ（deprecated を持つタグ）に当たる	索引の docs[0].tags[2]

duplicate_term の file と where は、重なった組のうち後の側を指す。 後の側は、索引、索引の docs の順の文書の順で、後に出た方。 索引の側は、file が indexFile、where が terms[1].term か terms[1].aliases[0] の形になる。 用語集の表の側は、file が文書のパス、where が表のその行の文書の中の行番号（12 行目）になる。 message に、後の側に記載した表記と、もう片方の場所を書く。

avoided_term の file は、やめた言い方が出た文書のパス。 message に、やめた言い方と、代わりに使う用語の語を書く。 用語集の表のやめた言い方は、表を持たない文書も含めて、索引の全ての文書で探す。 同じやめた言い方が複数の用語にあるときは、索引の terms、索引の docs の順の文書の表の順で、先の用語の語を書く。 索引の docs にあって documents に渡された文書だけを探し、索引に無い文書は探さない。 探す範囲と語の切れ目は文書の別名と同じで、コード・リンク・見出し・用語集の表の中は探さない。 やめた言い方と本文の文字は、正規化して比べる。 やめた言い方が用語の語・別名の一部として出たところ（ワーク をやめた言い方にしたときの ワークスペース）は数えない。 同じ行に同じやめた言い方が 2 回出ても 1 件で、行が違えば別の件になる。

related_link_overlap は、本文を渡していない文書では確かめない。 リンクの比べ方は被参照と同じで、本文でリンクしている相手は、related から外すか本文のリンクを外して、どちらか一方にする。

missed_change_together の file は、変わっていない側の文書のパス。 message に、変わった側の文書のパスと、変わっていない側も直すか確かめることを書く。 組は向きを問わず 1 回だけ確かめ、相手が索引に無い組は確かめない。 比べる基準から変わった文書のパスを渡すのは、checkIndex の changedPaths、mdmark check の --base、MCP の check の base（API・CLI・MCP）。

file は、索引のずれが indexFile、文書のずれがその文書のパス。 message に、ずれの内容と直す場所を日本語の 1 文で書く。

タグのずれ

duplicate_tag・tag_alias_conflict・broken_tag_replacement・unregistered_tag・deprecated_tag は、索引がタグの語彙（最上位の tags）を記載しているときだけ返す。 語彙を記載していない索引では、タグのずれを返さない。 どれも文書の読み込みを止めず、描くことには効かない。

文書のタグは、語彙の name か aliases に同じ文字で当たれば、そのタグの name として扱う。 同じ name・別名が複数あるときは、語彙の並びで先のタグに当てる。

tag_alias_conflict の message に、重なった先のタグの name を書く。 unregistered_tag の message に、近いタグを書く。 近いタグは、やめたタグでないタグの name と aliases のうち、文書のタグとの編集距離（文字の挿入・削除・置換の回数）が 2 以下で最も小さいもので、同じ距離なら語彙の並びで先のタグ。 当たるものが無いときは、近いタグが無いことと、語彙に足すか文書のタグを直すことを書く。 deprecated_tag の message に、振り替え先のタグを書く。