created: 2025-09-08T08:17:46.656Z
pandoc の --self-contained がとても便利だった
ここ 1 年くらい、困ってもほとんど LLM に聞けばなんとかしてくれてしまうので、ほとんど困らず技術メモを書くこともなかったのだが、昨日に pandoc で困った。 pandoc のオプションや in/out が対応してるバリエーションが多すぎるようで LLM も混乱していたように見えた。
状況と要件
- コードブロック (
<pre><code>...) を含む日本語のマークダウンがたくさんある - 見栄え良いものにして人に渡したい
- ドキュメント量がかなり多いので PDF よりも html のほうが親切そう
- ただし、認証付きの Web サーバを用意するのは面倒くさい
- ローカルの html ファイルを
file://プロトコルで見てもらう
- ローカルの html ファイルを
最終的にこんなコマンドになった。
docker run --rm -v "$(pwd):/build" tttza/pandoc-latex-ja:latest \
"pandoc \
--from=markdown \
--to=html \
--highlight-style=pygments \
--include-in-header ./header.html \
--self-contained \
<(cat ./*.md) \
-o ./output.html"
実行すると *.md の内容を全部つなげて output.html ファイルとして出力される。
--include-in-header ./header.html
出力 html の <head> タグに任意のタグを入れることができる。
./header.html ファイルの内容はこれだけ。
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/water.css@2/out/water.css"
/>
今回は markdown と相性がいいクラスレスの water.css を使った。
--self-contained
この要件を満たすためのオプション。
ローカルの html ファイルを
file://プロトコルで見てもらう
ドキュメントにはこのように書いてあった。まさに今回の用途のためのオプション。これがあってよかった。
Produce a standalone HTML file with no external dependencies, using data: URIs to incorporate the contents of linked scripts, stylesheets, images, and videos.
The resulting file should be “self-contained,” in the sense that it needs no external files and no net access to be displayed properly by a browser.
これを使うとシンタックスハイライトの CSS や、前述の water.css の内容がすべて html の中に展開されて、スタンドアロンの html としてブラウザで見栄え良く表示できる。
nextjs とか hugo とか今どきのツールだと絶対に実装されない、まさに pandoc だから可能になっている機能なんだと思う。
