mdmark

文書を1枚にまとめる

設定の build を書き、mdmark build で複数の文書を 1 枚にまとめる手順

複数の Markdown を、文書の一覧と文書間のリンクで行き来できる、CDN を読まない 1 枚の HTML にして配るときに実行する。

前提

• 雛形を置く（設定ファイル mdmark.config.yaml を今のフォルダか上のフォルダに置いている）
• Node 24 以降
• 文書が外部ライブラリの印を持つときは、書き出す手元から設定の libraries の URL の先へ届く

手順

まとめる文書を決める

設定に build を書く

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

パスと glob は、設定ファイルのあるフォルダからの相対パスで書く。 キーは まとめる設定。

• include: まとめる Markdown の glob。必須
• exclude: include に当たった文書から外す glob
• glossary: 用語集の表を持つ文書。表の用語を、まとめた全ての文書で効かせる
• entry: 最初に開く文書。省くと include で最初に当たった文書
• out: 書き出す HTML のパス。必須

文書は include の glob の並びで並べ、同じ glob の中はパスの順に並べる。 複数の glob に当たった文書は、最初の 1 つだけを残す。

索引を書くと被参照が効く

設定の index に索引を書くと、索引と文書から参照の表を作って埋め、文書をまたぐ被参照と用語のツールチップが効く。 索引の書き方は 索引と用語集を書く。 索引が無くても、build.glossary の文書の用語集の表の用語は、まとめた全ての文書で効く。

まとめる

build を呼ぶ

npx github:shuhei1101/mdmark#v{版} build [--config {設定ファイル}]

--config を省くと、今のフォルダから上のフォルダへ順に mdmark.config.yaml を探す。 build.out に HTML を書き、既にあれば上書きする。

書き出した: dist/docs.html（文書 3 件）

埋まるものは 文書を書き出す と同じ。 外部ライブラリはまとめる文書のどれかに印があるものだけを埋め、同じ URL は 1 つだけ埋める。 画像はそれぞれの文書のフォルダを基準に読む。

警告を読む

文書を書き出す の警告に加えて、次を標準エラーに出す。 警告があっても終了コードは 0。

• まとめた HTML に含まれない文書へのリンク。リンクは書いたままの href で残る。まとめるなら build.include に足す
• build.glossary がまとめる文書に当たらないパス。飛ばす
• build.entry がまとめる文書に当たらないパス。まとめる文書の最初の 1 つを開く

警告: README.md: `下書き/メモ.md` へのリンクはまとめた HTML に含まれません。書いたままのリンクで残します。まとめるなら `build.include` に足してください。

まとめられないとき

設定ファイルが無い・読めない・Schema に合わないとき、設定に build が無いとき、build.include に当たり build.exclude に当たらない文書が 0 件のとき、build.out へ書けないときは、原因と直し方の 1 文を標準エラーに出し、終了コード 1 で終わる。 HTML は書かない。

読む

HTML を file:// で開く

まとめた HTML 1 つを、配る先へ写して開く。 開くと build.entry の文書が描かれ、画面の左に文書の一覧が並ぶ。 開いている文書の行は背景で示す。 開いてから文書を移っても、ページ自身と blob:・data: のほかへ要求しない。 開くブラウザは Chrome 99・Firefox 98・Safari 16.4 以上。

文書の一覧の文書を選ぶ、まとめた文書へのリンクを押す、関連文書のリンクを押すと、1 枚の中の文書へ移る。 移った文書をブラウザの戻る・進むで行き来できる。 見出しのアンカーと目次のリンクは、移った先の文書の中で効く。

開いている文書と見出しは URL の # が指し、#/{文書のパス} か #/{文書のパス}#{見出しの ID} の形で書く。 # が文書を指していないか、まとめた文書に無い文書を指しているときは、build.entry の文書を出す。

幅が 60rem 未満では文書の一覧を左に置かず、文書の上の帯の「文書の一覧」のボタンで、一覧のパネルを重ねて開く。 文書を選ぶ・背景を押す・Esc・閉じるボタンでパネルを閉じる。 パネルの開閉は履歴に積まない。

印刷では文書の一覧を出さず、開いている文書だけを出す。 見た目は、設定の theme の CSS で変える（テーマを上書きする）。 開いている文書の行の背景は、CSS 変数 --mdmark-color-current-bg で変える。

反映

即時。build が終わると、build.out に HTML が書かれている。

確認

HTML が書かれている

build.out のパスに HTML があり、標準出力に 書き出した: {build.out}（文書 {件数} 件） の行が出て、終了コードが 0 になる。 件数が、まとめたい文書の数と合っている。

文書を行き来できる

HTML だけを空のフォルダへ写して file:// で開く。 build.entry の文書が描かれ、文書の一覧にまとめた文書が並ぶ。 一覧で別の文書を選ぶと、その文書が描かれ、ブラウザの戻るで元の文書に戻る。 ブラウザの開発者ツールのネットワークに、ページ自身と blob:・data: のほかの要求が出ない。

元に戻す

build.out の HTML を消す。 設定の build・文書・索引は build が書き換えない。