【2026年】Pandoc ドキュメント変換ガイド｜あらゆる形式を相互変換

2026 年最新！Pandoc ドキュメント変換ガイド｜あらゆる形式を相互変換

ドキュメント作成の現場において、フォーマットの変換は常に重要な課題です。2025 年から 2026 年にかけて、技術文書や論文発表、電子書籍発行の需要が増加し続ける中、単一のツールで多様な形式へ対応できる「万能変換機」の重要性がさらに高まっています。本記事では、Haskell で開発されたユニバーサルドキュメント変換ツールの「Pandoc 3.x」シリーズを中心に、Markdown から PDF、DOCX、EPUB への完全な変換ワークフローを解説します。

John MacFarlane 氏によってメンテナンスされ続けるこのツールは、単なる形式変換にとどまらず、LaTeX エンジンや Lua フィルターを活用した高度なカスタマイズも可能にしています。本ガイドでは、2026 年時点での最適設定を提示し、CJK（中日韓）フォントの扱い方から、CI/CD による自動化パイプライン構築まで、具体的な数値と製品名を交えて詳細に解説します。初心者から中級者に向けて、専門用語は初出時に簡潔に説明しつつ、E-E-A-T の原則に従った信頼性の高い情報を提供していきます。

Pandoc とは何か？ユニバーサル変換の核心

Pandoc（パンドック）とは、アラン・マクファーレン氏によって 2006 年に開発され、現在も活発にメンテナンスが続いている汎用ドキュメント変換ツールです。このソフトウェアは Haskell という関数型プログラミング言語で書かれており、その設計思想により、極めて高い抽象化レベルでのテキスト処理を可能にしています。Pandoc の核心となる概念は「中間表現（Abstract Syntax Tree：AST）」の存在です。入力されたドキュメントは一旦 Pandoc 独自の JSON 形式の AST に変換され、その後、出力先の形式に合わせて再度コンパイルされます。このプロセスにより、Markdown から LaTeX、DOCX から EPUB へといった、互いに構造が異なる形式間での高精度な変換が実現されています。

2025 年にリリースされた Pandoc 3.x シリーズは、従来のバージョンとの互換性を保ちつつ、新たな機能強化を遂げています。具体的には、Typst という最新の typesetting system との統合が深化し、HTML5 の記述仕様に対する対応も改良されています。また、Lua フィルターによるカスタム処理の実行速度が向上しており、大規模なドキュメント（例えば 10 万語以上の論文やマニュアル）の変換時間も短縮されつつあります。バージョン番号の表記においても、2026 年現在では「3.1.9」以降が安定版として推奨されており、セキュリティパッチも定期的に適用されています。

このツールの利点は、単に形式を変換するだけでなく、「ドキュメントの構造情報」を保持できる点にあります。例えば、Markdown で記述された見出しは、PDF に変換しても適切なヘッダーレベルとして認識され、目次生成アルゴリズムにも正しく組み込まれます。逆に、Word の DOCX ファイルから Markdown を出力する際も、スタイル情報を保持した見出しやリストが復元されます。このため、Pandoc は「ドキュメントエンジニアリング」の現場において不可欠なインフラツールとなっています。2026 年の現在では、個人開発者から大企業の技術文書チームまで、約 4,500 ユーザーコミュニティが活発に活動しており、不具合報告や機能要望が迅速に対応される環境も整っています。

対応形式一覧と変換パイプラインの実践

Pandoc が対応する入力・出力形式は非常に多岐にわたり、現在では 40 種類以上のフォーマットをサポートしています。代表的な形式としては、軽量マークアップ言語の Markdown（.md）、LaTeX（.tex）、HTML5（.html）が含まれます。また、オフィス文書形式である Microsoft Word の DOCX（.docx）や、電子書籍標準の EPUB3（.epub）への対応も堅牢です。近年注目されているのは、AsciiDoc や reStructuredText、そして 2025 年頃から本格的にサポートが強化された Typst です。Typst は高速な typesetting エンジンとして知られ、Pandoc を介して Markdown から Typst への変換が可能になりつつあります。

変換パイプラインを構築する際、入力形式と出力形式の組み合わせによって、品質や互換性に大きな差が生じます。例えば、Markdown から PDF を生成する場合、LaTeX エンジンの選定が重要です。一方、DOCX への変換では、Word のスタイル定義とのマッピング精度が課題となります。下表は主要な変換パスにおける特徴と推奨設定をまとめたものです。これらを理解することで、目的に応じた最適な変換コマンドを選択することが可能になります。

また、2026 年時点での最新動向として、Pandoc は Docker コンテナ内で動作するイメージを公式に提供しており、環境構築の負荷を大幅に軽減しています。Docker イメージ名は pandoc/core:3.1 が標準です。これにより、Windows や macOS、Linux のいずれの OS 上でも、同じ設定で結果の揃ったドキュメント生成が可能になります。ファイルサイズについても、PDF 変換時の圧縮率を指定できるオプション（--pdf-engine-opt）が用意されており、送信用には 5MB 以下に抑えるといった指定も可能です。

変換パイプラインの実践においては、単発のコマンド実行だけでなく、複数ステップでの処理が求められるケースが大半です。例えば、Markdown で記述した内容に対して、まず Lua フィルターで特定のテキストを置換し、次に LaTeX テンプレートを適用して PDF 化するような流れです。この場合、各ステップの中間ファイルを管理する必要があります。2025 年以降の Pandoc では、これらの中間ファイルを自動的にテンポラリディレクトリに保存する機能も強化されており、手動でのファイル管理が不要になっています。

基本コマンドの理解と引数の意味

Pandoc の使用において最も基礎的かつ重要な要素は、コマンドラインにおける引数（フラグ）の正しい指定です。代表的な基本構文は pandoc input.md -o output.pdf という形になりますが、これだけでは不十分なケースがほとんどです。例えば、入力形式を明示する --from=markdown や、出力形式を --to=pdf で指定するオプションは、Pandoc がファイル拡張子から推測できない場合に必須となります。特に、拡張子が不明なファイルや、標準とは異なる拡張子を使用している場合は、この引数による指定が変換の成否を分けます。

重要な引数の一つに --standalone（または -s）があります。これは、出力ファイルを単独で閲覧可能な形式に変換するためのフラグです。PDF 生成時、このオプションがないと LaTeX のプレアンプル部分や CSS が不足し、変換後にエラーが発生したり、見た目が崩れたりする可能性があります。また、メタデータを外部ファイルから読み込む --metadata-file=config.yaml も重要な機能です。これにより、ドキュメントの著者名、作成日、タイトルといった情報を Markdown ファイル内に記述せずとも管理でき、テンプレート側で一括制御が可能になります。

さらに、2026 年現在では、エラーメッセージの表示形式も改善されています。変換時にフォントが見つからない場合や、パス指定が誤っている場合は、具体的なファイルパスとエラーコードが表示されます。例えば Error: cannot find font 'Noto Sans CJK JP' のような表示が出た際は、システムにインストールされているフォント名を確認する必要があります。また、処理ログのレベルを調整する --verbose（または -v）オプションを使用することで、変換プロセスの詳細情報を出力できます。デバッグ時には -vvv とすると、AST 解析から最終レンダリングまでの全工程がログ出力され、ボトルネック箇所の特定に役立ちます。

引数の組み合わせには注意が必要です。例えば、PDF 生成時に --pdf-engine=pdflatex と指定した場合、日本語フォントがサポートされていないため文字化けが発生します。この場合、明示的に --pdf-engine=xelatex を追加する必要があります。また、2026 年版の Pandoc では、オプションのデフォルト値が一部変更されています。例えば、HTML5 の出力において、以前は --standalone で CSS が自動的に生成されていましたが、現在はよりモダンなスタイルを指定する --css=style.css を併用することが推奨されています。

Markdown から PDF を生成する完全ガイド

日本語ドキュメントを PDF として出力する場合、最も重要なのがフォント設定と LaTeX エンジンの選定です。Pandoc は標準で LaTeX のコンパイルエンジン（pdfLaTeX, XeLaTeX, LuaLaTeX など）を使用しますが、日本語の文字コード処理においては XeLaTeX または LuaLaTeX が推奨されます。なぜなら、これらは OS にインストールされているシステムフォントを直接参照できるためです。一方、標準の pdfLaTeX では日本語フォントのマッピングが複雑で、環境構築に時間がかかります。2026 年現在では、MacOS や Windows のユーザーは、これらのエンジンを事前インストール済みであるケースが大半ですが、Linux ユーザーでは TeX Live 等のパッケージ管理が必要になります。

具体的なコマンドの例として、日本語フォント「Noto Sans CJK JP」を使用する場合の設定を示します。これは Google が開発したオープンソースのフォントで、多言語に対応しています。Pandoc の設定ファイル（pandoc.yml）やコマンドライン引数で、このフォントを指定する必要があります。また、PDF 生成には --pdf-engine=xelatex を指定し、さらに --variable=mainfont='Noto Sans CJK JP' でメインの日本語フォントを設定します。この設定により、見出しや本文が美しく表示され、印刷物としても十分な品質を確保できます。

また、A4 サイズや B5 サイズといった用紙サイズの変更も可能です。コマンド引数 --variable=geometry:margin=2cm とすることで、余白を調整したり、--variable=papersize=a4paper で用紙サイズを指定できます。さらに、ヘッダーやフッターにページ番号やタイトルを自動挿入する設定も、Pandoc のメタデータ機能と結合することで実現可能です。例えば、著者名を author: "田中太郎" と定義し、テンプレートで {author} を参照させることで、すべての PDF に統一された署名が追加されます。

PDF 生成における品質の維持には、画像の解像度管理も含まれます。Markdown ファイル内に埋め込まれた画像は、変換時に LaTeX 形式に組み込まれます。高解像度の画像を使用すると、ファイルサイズが膨れ上がるため、--pdf-engine-opt=--interaction=nonstopmode を使用してエラーを回避しつつ、画像の圧縮設定（DPI）を指定することがあります。例えば、Web 公開用であれば 72 DPI、印刷物向けには 300 DPI を目指すなど、用途に応じた最適化が必要です。

Eisvogel とカスタムテンプレートの活用

Pandoc の PDF 生成において、見た目やレイアウトは LaTeX テンプレートに依存します。最も広く使われているテンプレートが「Eisvogel」です。これは 2025 年時点でも actively maintained（活発にメンテナンス中）されており、学術論文や技術文書に適した洗練されたデザインを提供しています。Eisvogel を使用するには、GitHub リポジトリから最新の .tex ファイルをダウンロードし、Pandoc の設定で指定する必要があります。具体的には --template=eisvogel.tex という引数を追加するだけで、標準の PDF 出力が大幅に改善されます。

Eisvogel テンプレートの特徴は、見出しのスタイル、目次、リスト、表、脚注などの配置が最適化されている点です。また、ダークモード対応や、特定の学術書式（APA, IEEE など）への対応も可能です。2026 年の現在では、Eisvogel のバージョン 3.5 以上を使用することで、PDF ファイル内のブックマーク機能が自動的に有効になり、電子文書としての利便性が向上しています。さらに、カスタム CSS を適用して色指定やフォントサイズを細かく調整することも可能です。

広告

カスタムテンプレートを作成する際には、Pandoc のテンプレート構文を理解する必要があります。これは Jinja2 テンプレートエンジンに似た構文を使用しており、変数（{title}）やループ処理（$for(author)$...$endfor$）が可能です。例えば、著者名が複数いる場合に改行を入れるなどのロジックを記述できます。テンプレートファイルは ~/.pandoc/templates/ ディレクトリに配置することで、すべてのプロジェクトで利用可能になります。

カスタムテンプレートを使用する際の注意点として、ファイルの保存形式が UTF-8 であることが挙げられます。日本語を含むコメントや変数記述を行う場合、エンコーディングが間違っているとコンパイルエラーの原因となります。また、テンプレート内の LaTeX コードを変更した場合は、その後の Pandoc バージョンアップとの互換性を確認する必要があります。2025 年以降の Pandoc では、テンプレートの構文チェック機能が強化されており、エラーが発生する前に警告を出すようになりましたが、手動での検証は依然として重要です。

DOCX と EPUB の作成と編集

Microsoft Word の DOCX ファイルや電子書籍の EPUB3 形式への出力も、Pandoc の主要な用途の一つです。DOCX への変換を行う際、最も重要なのはスタイル定義（Style Definition）のマッピングです。Markdown の見出しレベル（H1, H2 など）が、Word の「タイトル 1」「タイトル 2」などのスタイルに正しく対応する必要があります。これを手動で行うのは困難なため、Pandoc は --reference-doc=<styles.docx> オプションを提供しています。これにより、特定の Word ファイル内のスタイル設定を、変換先のドキュメントへ反映させることができます。

EPUB3 形式への対応については、電子書籍リーダー（Kindle, Apple Books など）での表示を考慮する必要があります。Pandoc は EPUB3 の標準である EPUB3.2 に準拠した出力を行いますが、画像の埋め込み方法や CSS の記述がリーダーによって解釈される場合があります。特に「リフロー型」と「固定レイアウト型」の違いに注意が必要です。リフロー型は文字サイズ変更に対応しますが、表組などが崩れる可能性があります。EPUB 生成時には --epub-cover-image オプションで表紙画像を設定し、メタデータとして ISBN や著者情報を埋め込むことが推奨されます。

また、2026 年時点では、EPUB3 のアクセシビリティ機能（Accessibility）への対応が強化されています。Alt テキストの付与や、読み上げ順序の指定など、障害を持つユーザーも閲覧できるドキュメント作成が可能になっています。Pandoc では --epub-subtitle や --epub-language=ja-JP といった引数で言語設定も行え、スクリーンリーダーが日本語として認識するようになります。

DOCX ファイルから Markdown を出力する際にも注意が必要です。Word の複雑な書式設定は、Pandoc では単純化されることがあります。例えば、表組みのスタイルや列幅などは失われる可能性があります。このため、Docx 出力時には --reference-doc で事前に整形されたテンプレートファイルを使用し、変換後の編集コストを最小化する工夫が求められます。また、Word の「コメント機能」は Markdown では直接表現できないため、JSON データとして別ファイルへ出力するオプションや、注釈としてテキスト化して埋め込む処理が必要です。

Lua フィルターと pandoc-crossref の拡張機能

Pandoc の真価が発揮されるのが、Lua フィルターによるカスタム処理です。Lua は軽量なスクリプト言語であり、Pandoc の AST（抽象構文木）を直接操作して変換ロジックを記述できます。例えば、「特定のキーワードを含む行にハイライトを加える」「自動で目次を追加する」「数式ブロックのフォーマットを変更する」といった処理が可能です。2026 年現在では、コミュニティによる Lua フィルターライブラリが充実しており、これらの機能を実装し直す必要なく利用できます。

特に「pandoc-crossref」は、論文や技術文書において必須となる相互参照機能を強化します。通常の Pandoc では見出しや図表へのリンク（「図 1 のように...」）を自動生成することが難しいですが、pandoc-crossref フィルターを使用することで、番号付きのセクションや図表に対するクロスレファレンスが自動的に解決されます。これにより、ページ数が変更されてもリンク切れが発生しないドキュメントが生成可能です。

Lua フィルターの基本的な書き方は、function Header(elem) のように特定のブロックタイプに動作を定義します。例えば、Header 要素を取得し、その内容を大文字に変換して出力する処理などは簡単です。より高度な例として、Markdown の注釈記法（[^1]）を HTML の footnote 形式へ変換するロジックも Lua で実装可能です。これにより、Pandoc の標準機能では対応できない特殊なフォーマット変換を実現できます。

Lua フィルターを使用する際は、Pandoc のバージョンとの互換性を確認する必要があります。2025 年のアップデート以降、Lua フィルターの API が一部変更されており、古いスクリプトが動作しないケースがあります。そのため、フィルターの更新履歴（CHANGELOG）を確認し、最新版の Pandoc で動作確認を行うことが推奨されます。また、フィルターの実行順序も重要で、--filter の複数指定は左から右へ順に処理されます。出力結果に影響を与える順序変更が必要な場合は、フィルターの依存関係を整理した上で実行する必要があります。

CI/CD と自動化パイプラインの構築

ドキュメント生成の効率化において、手動でのコマンド実行は非現実的です。2026 年現在では、CI/CD（Continuous Integration / Continuous Deployment）システムや Makefile を活用した自動化が標準となっています。GitHub Actions を利用すると、コードがリポジトリにプッシュされた際に自動的にドキュメントを生成し、Artifacts としてアーカイブできます。これにより、常に最新のビルド結果を確認可能になります。

広告

Makefile を作成することで、複雑な変換プロセスを一発コマンドで実行できるようになります。例えば make pdf コマンドを実行するだけで、Markdown ファイルを検索、変換、PDF エンジンへ渡し、最終的なファイルが生成されます。これにより、開発者や編集者が個別に環境設定を行う必要がなくなります。Docker コンテナを介して Pandoc を実行することで、ローカル OS の違いによるバグも排除できます。

自動化パイプラインの具体例として、GitHub Actions のワークフローファイルを記述します。これには actions/setup-node@v3 や pandoc/core:3.1 イメージを使用し、変換プロセスを定義します。また、生成された PDF ファイルは GitHub Pages へデプロイすることも可能です。これにより、ドキュメントの公開が自動化され、URL を共有するだけで最新情報を閲覧できます。

自動化における注意点として、セキュリティ情報の扱いがあります。ドキュメント生成プロセスに個人情報が含まれる場合や、秘密鍵を必要とする場合は、CI/CD のシークレット管理機能を使用する必要があります。また、変換時間のロギングも重要です。大規模なドキュメントの場合、ビルドが失敗する前にタイムアウトになる可能性があります。このため、GitHub Actions などで timeout-minutes を適切に設定し、長期処理に対応した環境構成を行うことが求められます。

よくある質問（FAQ）

Q1. Markdown ファイルを PDF に変換したら日本語が化けます。どうすればよいですか？ A1. これは PDF エンジンの問題である可能性が高いです。デフォルトの pdflatex は日本語に非対応です。コマンドに --pdf-engine=xelatex または --pdf-engine=lualatex を追加してください。また、使用するシステムフォント（例：Noto Sans CJK JP）が OS に正しくインストールされているか確認が必要です。

Q2. DOCX 出力時にスタイルが崩れてしまいます。 A2. Word のスタイル定義を参照ファイルとして指定する --reference-doc オプションを使用してください。事前に整形された .docx ファイルを用意し、そのスタイル情報をコピーして変換に使用することで、見出しやリストの見た目を統一できます。

Q3. 図表への自動番号付け（クロスリファレンス）をしたいです。 A3. Pandoc の標準機能だけでは不十分です。「pandoc-crossref」という Lua フィルターを使用してください。コマンドラインに --filter=pandoc-crossref を追加することで、見出しや図表へのリンクが自動的に解決されます。

Q4. 大量の Markdown ファイルを一度に変換したいです。 A4. 単一の Pandoc コマンドでは対応しきれない場合があります。Makefile を使用してループ処理を行うか、スクリプト（Python や Bash）でファイルを巡回させ、変換コマンドを実行するように自動化してください。

Q5. PDF ファイルのサイズが大きすぎます。圧縮する方法はありますか？ A5. --pdf-engine-opt オプションを使用して LaTeX エンジンの設定を渡すことができます。例えば XeLaTeX に対して --pdf-engine-opt="-interaction=nonstopmode" を指定し、画像の DPI 設定を変更することでファイルサイズを調整できます。

Q6. Eisvogel テンプレートを使用したいのですが、どこで入手できますか？ A6. GitHub の公式リポジトリ（https://github.com/wkh237/pandoc-template-eisvogel）から最新の .tex ファイルをダウンロードしてください。Pandoc の実行ディレクトリに配置するか、--template オプションで指定します。

Q7. 変換中にエラーが発生して止まってしまいます。 A7. --verbose または -vvv オプションを使用して詳細ログを確認してください。エラーメッセージに含まれる行番号やファイル名から原因を特定できます。フォントの不足や、テンプレートファイルの不整合が主な原因です。

Q8. Docker を使って Pandoc を実行したいのですが、コマンドはどうなりますか？ A8. docker run -v $(pwd):/data pandoc/core:3.1 /data/input.md -o /data/output.pdf のように、ローカルディレクトリをマウントしてコンテナ内で実行します。これにより OS 依存のない環境で変換が可能です。

Q9. EPUB ファイルの表紙画像を設定する方法は？ A9. --epub-cover-image=<path_to_image> オプションを使用します。画像ファイルのパスを指定することで、EPUB のメタデータに表紙情報として埋め込まれます。

Q10. 2026 年現在で推奨される Pandoc のバージョンは何ですか？ A10. 安定版は「3.x シリーズ」です。具体的には 3.1.9 以降が推奨され、セキュリティパッチや新機能（Typst 対応など）が含まれています。最新情報は GitHub のリリースページを確認してください。

まとめ

本記事では、Pandoc を用いたドキュメント変換の完全ガイドを解説しました。

• Pandoc の核心: Haskell で書かれた AST ベースの変換エンジンであり、形式間の高精度な互換性を保証する。2026 年現在は Pandoc 3.x シリーズが標準として推奨される。
• 対応形式: Markdown, LaTeX, HTML, DOCX, EPUB, Typst など 40 種以上の形式に対応し、用途に応じた選択が可能である。
• PDF 生成: 日本語対応には XeLaTeX または LuaLaTeX エンジンが必要であり、「Noto Sans CJK JP」などのシステムフォントを使用することが推奨される。
• テンプレート活用: Eisvogel テンプレートによる美観の向上や、カスタムテンプレートでのスタイル制御が可能である。
• 拡張機能: Lua フィルターや pandoc-crossref を使用することで、高度なカスタマイズや相互参照機能が実現できる。
• 自動化: Makefile や GitHub Actions による CI/CD パイプライン構築により、継続的なドキュメント生成と管理が可能になる。

これらの知識を組み合わせることで、2026 年現在の技術文書作成環境において、効率的かつ高品質なドキュメント生産ラインを確立することができます。ぜひ本ガイドを参考に、あなたのワークフローの最適化に役立ててください。