mdmark

文書を描く

配布物を読んだページで mount を呼び、要素の中に Markdown を描く

mdmark を読み込んだページに、文書を初めて描くとき、本文を差し替えるとき、描いた文書を片付けるときに実行する。

前提

手順

描く

描く先の要素を置く

<div id="doc"></div>

要素が無いと、文書は描かれない。

mount を呼ぶ

<script type="module">
  import { mount } from "https://cdn.jsdelivr.net/gh/shuhei1101/mdmark@{タグ}/dist/index.js";

  const handle = mount(document.querySelector("#doc"), { markdown: "# 見出し\n\n本文" });
</script>

{タグ} は CSS を読み込んだタグに置き換える。 同じ要素へもう一度 mount を呼ぶと、前の描画を片付けてから描く。

設定を渡す

使う側のサーバーが mdmark.config.yaml を読んだオブジェクトを、config に渡す。

mount(document.querySelector("#doc"), { markdown, config: { features: { print: false } } });

省いたキーには既定を当てる。 キーは 設定。

索引と文書の id を渡す

使う側のサーバーが読んだ索引のオブジェクトと、描く文書の索引の id を渡す。

mount(document.querySelector("#doc"), { markdown, index, docId: "arch", references });

references は collectReferences が返した参照の表で、省ける。 本文に出た用語に意味のツールチップが付き、文書の末尾に被参照の一覧が出る。 索引の書き方と参照の表の作り方は 索引と用語集を書く。

本文を差し替える

update を呼ぶ

handle.update("# 次の見出し");

本文だけを描き直す。 設定は mount に渡したものを使う。 設定を変えるときは、mount を呼び直す。

片付ける

destroy を呼ぶ

handle.destroy();

要素の中を空にして class mdmark を外し、印刷の受け取りを外す。 呼んだ後の update は何もしない。

Webview に組み込む

CSP に要るものを許す

VS Code の拡張機能の Webview のように CSP を付けたページに描くときは、次を許す。

ディレクティブ 許すもの
script-src 配布物の配信元（https://cdn.jsdelivr.net）。外部ライブラリを使うときは、設定の libraries の URL の配信元。読み込む script に付ける nonce
style-src 配布物の配信元と 'unsafe-inline'
font-src 配布物の配信元
img-src 本文の画像の配信元

図とヒントの部品が HTML に style 属性を付けるため、style-src に 'unsafe-inline' が要る。 スクリプトは nonce で絞れる。

印刷は Webview の外で行う

Webview の中では、印刷（window.print()）が効かない。 印刷や PDF が要るときは、文書を HTML に書き出してブラウザで開き、そこで印刷する（HTMLとPDFにする）。

反映

即時。mount を呼ぶと、その場で描かれる。

確認

文書が描かれている

document.querySelector("#doc").classList.contains("mdmark")

true が出る。 要素の中に、Markdown に書いた見出しと本文が描かれている。

見た目が当たっている

要素に地の色と内側の余白が付き、本文が既定では 46rem までの幅で表示される。 当たっていないときは、配布物を読み込む の確認で CSS が読み込まれているかを確かめる。

元に戻す

destroy を呼ぶ。 ページから mount の呼び出しと描く先の要素を消すと、mdmark が描いたものは残らない。