MarkdownをHTMLに変換

フラグメントかページか、どちらが必要か

便利な出力は2種類あり、互いに置き換えはききません。フラグメントは変換されたマークアップだけ、つまり見出し、段落、リスト、リンクで、文書全体を包む部分はありません。結果をテンプレートやCMSの入力欄、別のページに入れる場合はこちらを使います。完全なページにはdoctype、head、文字コードの宣言、スタイルシートが加わるため、単体で開けて見栄えも整います。完全なページをCMSに貼り付けると文書の中に文書ができてしまい、フラグメントをブラウザで開くとスタイルのないテキストになります。

変換は、広く合意されている拡張Markdownの範囲に対応しています。見出し、強調、リスト、リンク、画像、引用、表、シンタックスハイライト付きのコードブロック、タスクリスト、取り消し線、脚注です。見出しにはテキストから作られたIDが付くため、直接リンクできます。長いドキュメントを使いやすくするアンカーリンクです。

Markdown内の生のHTMLはそのまま通されます。これは仕様の一部であり、意識しておく価値があります。つまり、信頼できない相手から受け取ったMarkdownファイルにはscriptタグが含まれている可能性があり、それを変換するとそのスクリプトを含むページができあがります。見知らぬ相手のMarkdownを表示するときは、必ず後からHTMLをサニタイズしてください。変換処理はセキュリティの境界ではなく、そのように作られたものでもありません。

次の2つは、意図的に描画せずコードブロックとして出力します。LaTeX記法の数式には組版ライブラリが、Mermaidの図には図のレンダラーが必要です。どちらも大きな依存関係になりますし、誤って描画された数式は、そのまま見える数式よりも害があります。完全なページはフォントを読み込まず一般的なシステムフォントを使うため、オフラインでも動作し、Windows、macOS、Linuxで見た目が少し異なります。

ほかの目的には

Pandocなら、ここで省いた部分をはじめ、さらに多くのことができます。pandoc in.md -o out.html --mathjax --standalone --tocで数式を正しく描画し、目次を生成し、テンプレートを指定して出力をご自身のサイトに合わせられます。ほかにも約40の形式との相互変換に対応しているので、一度インストールしておく価値があります。

ファイルではなくWebサイトを作るなら、ページを1つずつ変換するのではなくジェネレーターを使いましょう。Hugo、Eleventy、Jekyll、MkDocsは、Markdownのフォルダーをナビゲーション、検索、統一されたスタイルを備えたサイトに変換し、元のファイルが変わるたびに再構築します。文書が2つ以上あるなら、本当に必要なのはこちらです。