mdmark

1枚にまとめる仕組み

文書を集めて参照の表を作り、配布物・CSS・外部ライブラリ・画像と一緒に 1 枚に埋める流れ

mdmark export と mdmark build が、Markdown から CDN を読まない 1 枚の HTML を書き出し、その HTML が開かれて文書が描かれるまでの考え方。 手順は 書き出す。

書き出すまでの流れ

1. 設定ファイル mdmark.config.yaml を読み、Schema に合うかを確かめる。mdmark build は、設定の build の include・exclude でまとめる文書を決める
2. 設定の index があるとき、索引と、索引の docs の文書を読み、collectReferences で参照の表を作る
3. 文書の印にある外部ライブラリを、設定の libraries の URL から読み、モジュールが import する先も含めて URL ごとに 1 つの ES モジュールに束ねる。設定の extensions の拡張のモジュールも、1 つずつ束ねる
   • 文書に色分けする言語のコードブロックがあるときは、設定の syntax.url から色分けのライブラリの本体と、文書が使う言語のモジュールだけを、1 つずつ束ねる
4. 文書が相対パスで指す画像を読み、data: URL に替える
5. 配布物の CSS、設定の theme の CSS、設定・索引・参照の表・文書の Markdown、束ねたモジュールと拡張、起動の処理を、1 枚の HTML に埋めて書く

文書に書いたスクリプトは、render と同じサニタイズで落とし、書き出した HTML でも実行しない。 読めない画像・モジュール・拡張・CSS は、書き出しを止めず警告に出す。

開いたときの流れ

1. 起動の処理が、埋めた中身を読む
2. 埋めたモジュールを blob: URL に替え、設定の libraries に渡す。埋めた拡張を、描く前に registerExtension で登録する
3. 文書を mount で描く。描かれる本文は render と同じで、記法の操作・用語のツールチップ・被参照も mount で付く

ページ自身と blob:・data: のほかへ要求しないため、file:// で開いても、CDN を読めない環境でも、1 枚で描き終える。 外部ライブラリのモジュールは、mount の動的 import() が blob: URL から読む。 色分けも、mount が描いた後に、埋めた本体と言語のモジュールから色を付ける。 埋めなかった言語のコードブロックは、読みに行かずに色分けせず残す。

まとめた HTML の文書の行き来

mdmark build の HTML は、まとめた全ての文書をパスで引ける形で埋め、文書の一覧と、開いている文書を並べる。 開く文書と見出しは URL の # が #/{文書のパス}#{見出しの ID} の形で指し、指していないときは build.entry の文書を出す。

• 文書の一覧で選ぶ、まとめた文書へのリンクと関連文書のリンクを押すと、URL の # を替えて 1 枚の中の文書へ移り、履歴に積む
• ブラウザの戻る・進むで、移った文書を行き来する
• 見出しのアンカーと目次のリンクは、移った先の文書の中の見出しへ移る
• まとめた文書に含まれない文書へのリンクは、書いたままの href で残る。mdmark build が警告に出す

mdmark export の HTML は文書を 1 つだけ持つため、文書間のリンクは全て書いたままの href で残る。 文書を行き来させたいときは mdmark build でまとめる。