mnmpep-readme

Pandoc を “実用的なドキュメント生成ツール” に変える拡張パック

mnmpep は、Pandoc の Markdown→HTML 変換を大幅に強化するユーティリティパックです。
導入するだけで、Pandoc の素っ気ない HTML を、読みやすく・使いやすく・実用的なドキュメントへと変換できます。

テーマやプラグインではなく、CSS・ヘッダーHTML・Luaフィルターを組み合わせて
Pandoc のビルド結果に機能性とデザインを直接付与するのが特徴です。

複数のMarkdownファイルをmnmpepを利用して仕上げたHTMLドキュメント例は、こちらをご覧ください。

mnmpepの概要

Pandocは、markdownドキュメントをHTMLに効率よく変換する強力な手段です。
ですが、変換されたHTMLドキュメントは、決して読みやすく、利用しやすい理想的なものではありません。

mnmpep は、Pandoc の初期状態を調整することなく、
即座に実用的な HTML ドキュメントを生成できるようにする拡張パックです。

mnmpepが提供するフォルダに含まれる CSS・ヘッダー HTML・Lua フィルターをビルド時に指定し、index.html の配置・編集など、いくつかの簡単な手順をこなすことで、Pandoc の出力 HTML に下記のような効果をもたらします。

1. 即座にドキュメントとして利用できる、整ったレイアウトの適用
   • 標準の、無機質でかつ見づらいレイアウトから即座にグレードアップできます
   • ダークモードに対応
   • css変数で色を定義しているため、色調の調整は容易です
2. 各ページを切り替え、SPA的にドキュメント全体に対してアクセス可能となる目次HTMLの配備
   • 各Markdown内にこまめにリンクを書く必要がなく、複数ファイルに渡るドキュメントを「一冊」としてまとめて扱えます
   • ドキュメント著者は、作成時に長大な1ファイル内の往復を強いられることがなくなります
   • 読者は、内容ごとに適切なページを探すことが出来るようになります
3. Markdownでの特殊記法を用いた、ページ内画像クリック時のモーダル表示機能の実現
   • ドキュメント著者は、ページ幅に合わせた画像サイズの調整の手間が必要なくなります
   • 読者は、画像の細部を確認することが容易になります
4. 脚注クリック時の挙動を、ドキュメント最下部脚注への強制移動から、画面下部からのポップアップ表示に変更
   • 脚注から戻る際に元の位置に迷う事も、時間をかけることもなくなります
   • 本文を見ながら脚注を見ることが出来るようになります
5. TOCをページ本体から分離し、ページ横からアクセス可能に
   • 1200px以上の表示環境下では、左側余白部分にTOCを常時表示
   • 1200px未満の表示環境下では、TOCをスライドメニュー化
6. mermaidコードブロックを、自動的にSVG画像に変換して本文中に埋め込み
7. ページ内やページ間遷移時のアニメーションと、ページセクション指定遷移時の指定セクション強調表示
   • 参照リンクから遷移したはいいが、参照箇所が分かりづらいという事がありません
8. 印刷用スタイルも調整済み

また、Markdownファイルをwordファイルにビルドする場合、luaフィルターを通じて、mermaidコードブロック内容を図としてpng画像化して埋め込むことも可能です。

Pandocとmnmpepの組み合わせは、あなたのMarkdownテキストを、現代HTMLの表現力を詰め込んだブラウザ用ドキュメントに高速で仕上げます。