--- title: "Pandocの使い方｜Markdownからdocx・PDF変換の手順と日本語出力の詰まり方" url: "https://www.issoh.co.jp/tech/details/17688/" published: 2026-09-18 updated: 2026-09-18 categories: ["開発"] publisher: "株式会社一創" --- # Pandocの使い方｜Markdownからdocx・PDF変換の手順と日本語出力の詰まり方 Pandocは、Markdownで書いた原稿をHTML・Word（docx）・PDF・EPUBなど別の形式へ変換するコマンドラインツールです。最新版は2026年8月28日にリリースされた3.11で、数式の扱いが`--math-method`へ統合され、MathMLが既定になりました。導入自体は1コマンドで終わりますが、PDF出力だけは事情が違い、別途LaTeX環境を入れないと変換が途中で止まります。この記事では、OS別のインストール、`-f`と`-t`による形式指定、docxのテンプレート継承、日本語PDFで要るパッケージの分岐、Dockerイメージを固定してCIへ載せる形までを、2026年9月時点の公式ドキュメントの記述に沿って手順の形で整理しました。 ## まとめ：Pandocに任せる変換と、手作業に残す工程の線引き 先に結論です。Pandocが効くのは、原稿をMarkdownやreStructuredTextで一元管理し、そこからHTML・docx・PDFを機械的に吐き出す片道の経路です。仕様書や手順書のように、中身の更新頻度が高く、配布形式だけが複数あるドキュメントが当てはまります。 逆に、Word上での最終調整が工程として確定している納品物では、Pandocを挟むと往復が増えて遅くなります。docxから戻す変換は、内部の中間表現に載らない情報が落ちるためです。片道に限定する、という一点さえ守れば運用は安定します。 導入でいちばん詰まるのはPDFです。HTMLやdocxは追加インストールなしで出ますが、PDFはLaTeXエンジンが別に要ります。日本語を含む場合は`--pdf-engine=lualatex`と`CJKmainfont`の組み合わせが基本線で、このときLaTeX側にluatexjaが入っている必要があります。 ## Pandoc 3.11の対応フォーマットと内部ASTを経由する変換の仕組み 使い方の前に、変換の経路を押さえておくと不具合の切り分けが速くなります。Pandocは入力形式から出力形式へ直接変換していません。 ### 入力・出力の橋渡しに内部ASTを挟む設計と、Haskell実装の影響 Pandocは入力をいったん内部の抽象構文木（AST）へ読み込み、そこから出力形式へ書き出す二段構えです。読み取り側をリーダー、書き出し側をライターと呼びます。この設計のため、入力形式がN種類・出力形式がM種類あっても、必要な変換器はN＋M個で済みます。Markdown・HTML・LaTeX・docx・EPUB・Typst・Jupyter notebookまで対応形式が広がっているのは、この構造によるものです。 実務上の意味は2つあります。ひとつは、変換が失敗したときに「読めていないのか、書き出せていないのか」を切り分けられること。`-t native`でASTそのものを出力すれば、リーダー側の解釈を目視できます。もうひとつは、出力形式に対応する概念がASTに無ければ情報が落ちること。Wordのコメントや変更履歴、段組みの細かい指定は、この経路を通りません。 本体はHaskellで書かれた単一バイナリで、実行時のランタイム依存がほぼありません。CIコンテナへ入れても余計なパッケージを引き連れてこない点は、後述のDocker運用で効いてきます。 ### 3.11で追加された–math-methodとMathML既定化による数式出力の変化 [公式のリリース一覧](https://pandoc.org/releases.html)によれば、3.11は2026年8月28日に出ています。変更点で実務に効くのは、数式の処理方法を指定する`--math-method`が追加され、従来の`--mathml`や`--mathjax`といった個別オプションがそこへ統合されたことです。あわせてMathMLが既定の処理方法になりました。 数式を含むMarkdownをHTMLへ変換しているスクリプトが手元にあるなら、出力の見た目が変わる可能性があります。MathJaxを前提にしたCSSやスクリプトタグを埋めている場合は、変換後のHTMLを一度目で確認してください。同じ3.11ではbash・zsh・fishのシェル補完が追加され、3.10.1ではTxt2Tags形式の出力（`t2t`）が増えています。 ## Windows・macOS・Linuxのインストール手順とPDF出力に必要なLaTeX 導入経路は主要OSすべてで複数用意されています。パッケージマネージャを使う形が、後々の更新も含めていちばん楽です。 ### winget・Homebrewなどパッケージマネージャ別の導入コマンドと版の確認 [公式のインストール手順](https://pandoc.org/installing.html)は、WindowsにMSIインストーラ・Chocolatey・winget・Conda Forge・ZIP配置を、macOSにpkgインストーラ・Homebrew・MacPorts・Conda Forgeを、Linuxに各ディストロのパッケージ・deb・tarball・ソースビルドを挙げています。どれを選んでも入るものは同じですが、配布元によって版が異なります。入れ終えたら`pandoc --version`で実際の版を確認してください。 ``` # Windows（winget） winget install --source winget --exact --id JohnMacFarlane.Pandoc # Windows（Chocolatey） choco install pandoc # macOS（Homebrew） brew install pandoc # Debian / Ubuntu sudo apt install pandoc # 導入確認 pandoc --version ``` この記事のコマンド例は3.11系を前提にしています。手元の版が古いと、後述する`--math-method`のように存在しないオプションが出てくるため、版の食い違いを先に潰しておくと余計な調査を減らせます。 ### PDF出力に別途要るTeX環境の選び分けとフォント不足時の追加手順 PandocはPDFを自前で組版しません。LaTeXエンジンなど外部のPDFエンジンへ渡す設計のため、PDF出力を使うならその環境を別に入れます。公式が推奨するのは、WindowsではMiKTeX、Linuxではパッケージマネージャ経由のTeX Liveです。macOSではMacTeXが4GBある点に触れ、その代わりにBasicTeXまたはTinyTexを使う選択肢を示しています。 BasicTeXのように小さい構成を選ぶと、変換時にフォントやパッケージが足りないというエラーが出ることがあります。公式がその対処として挙げているのは、`tlmgr install collection-fontsrecommended`の実行です。LaTeXそのものの位置づけや用語を先に整理しておきたい場合は、[LaTeXとは？読み方・TeXとの違い・使い方を解説](https://www.issoh.co.jp/tech/details/9718/)で組版エンジン側の全体像をまとめています。 ## 基本コマンドの形｜-f・-tでの形式指定と-sで自己完結HTMLを出す手順 コマンドの骨格は「入力ファイル」と「`-o`で出力先」の2つだけです。ここに形式指定と出力オプションを足していきます。 ### 拡張子からの推測と-f・-tでの明示指定・+EXTENSIONでの方言切り替え 入出力の形式は拡張子から推測されます。`pandoc spec.md -o spec.html`と書けば、Markdownを読んでHTMLを書き出します。推測に頼らず明示する場合に使う指定は、入力形式が`-f`（`--from`）、出力形式が`-t`（`--to`）です。標準入力から読ませる場合や、拡張子が実態と合っていない場合は明示が要ります。 Markdownには方言があり、Pandocはこれを拡張の足し引きで表現します。形式名のうしろに`+EXTENSION`または`-EXTENSION`を付ける書き方です。GitHub風の書式で書かれた原稿なら`-f gfm`、表や脚注の挙動だけ変えたいなら拡張単位で調整します。[公式マニュアル](https://pandoc.org/MANUAL.html)が形式ごとの対応拡張を列挙しているので、意図しない解釈が出たらまずここを引いてください。 ### \-sを付けないと断片しか出ない出力形式と–tocを効かせる条件 HTMLへ変換して「タグが足りない」と感じたときは、`-s`（`--standalone`）の付け忘れです。これを付けないとbody内の断片だけが出力されます。公式マニュアルは、`-s`がheadとbodyを含む自己完結したドキュメントを出すオプションであり、pdf・epub・docx・odtでは自動的に有効になると説明しています。HTMLやLaTeXへ出すときだけ、明示が要るということです。 目次を付ける`--toc`も同じ理屈で、`--standalone`との併用が前提になります。断片出力に目次だけ差し込んでも置き場所が無いためです。 ``` # 拡張子から推測して変換する pandoc spec.md -o spec.html # 形式を明示し、自己完結HTMLに目次を付ける pandoc -f markdown -t html5 -s --toc spec.md -o spec.html # GitHub風Markdownとして読ませる pandoc -f gfm spec.md -o spec.html # 読み取り結果のASTを確認する pandoc -t native spec.md ``` ## docx出力でレイアウトを揃える–reference-docとテンプレート運用 Word形式への変換は`-o spec.docx`で通ります。ただし素の出力は既定スタイルのままで、社内の書式には揃いません。 ### –reference-docで社内テンプレートの見出しスタイルを継承させる手順 公式マニュアルは`--reference-doc`を、docxやODT出力の際に参照ファイルのスタイルを使うオプションと定義しています。出力ファイルが引き継ぐのは、参照ドキュメント側で設定したスタイル定義です。手順としては、一度Pandocでdocxを出し、それをWordで開いて見出し1・見出し2・本文・表のスタイルを社内書式に直し、テンプレートとして保存してから参照させる流れになります。 注意点は、参照側で定義されていないスタイルには効かないことです。Pandocが使うスタイル名に対応する定義がテンプレートに無ければ、その要素は既定のまま出ます。ロゴ入りの表紙やヘッダーフッターを含めたい場合も、参照docx側に用意しておきます。 ``` # Word形式へ出力する pandoc spec.md -o spec.docx # 社内テンプレートのスタイルを継承する pandoc spec.md --reference-doc=template.docx -o spec.docx ``` ### docxから逆方向に変換するときに落ちる情報と、往復を避ける運用 Pandocは`pandoc spec.docx -o spec.md`のように逆方向の変換もできます。既存のWord資産をMarkdownへ寄せる初回移行では有効です。問題は往復させたときで、docxからMarkdownへ落とし、また戻す運用にすると、中間表現に載らない情報が消えます。変更履歴やコメント、テキストボックス、細かい段組みが該当します。 運用としては、移行時に一度だけ逆変換を通し、その後はMarkdownを原本と決めて片道に固定してください。原本が2箇所に分かれた時点で、どちらが最新か分からなくなります。この原本の一元化は、文書の版管理を仕組みとして設計する話につながります。社内の文書が部署ごとに散っていて、変換の自動化より前段の整理が要る状態なら、[文書管理システム開発](https://www.issoh.co.jp/service/business%5Fsystem/document-management/)の観点から棚卸しするほうが先です。 ## 日本語PDFで詰まる箇所｜lualatexとluatexjaの組み合わせと代替手段 日本語を含む原稿をPDFへ出そうとして、文字が消える・エラーで止まる、という詰まり方が最も多い箇所です。原因は既定エンジンにあります。 ### –pdf-engineの既定値とCJKmainfont指定時に要るパッケージ 公式マニュアルによれば、`--pdf-engine`に指定できるのはpdflatex・lualatex・xelatex・latexmk・tectonic・wkhtmltopdf・weasyprint・pagedjs-cli・prince・context・groff・pdfroff・typstです。既定値は出力の経路で変わり、LaTeX経由ならpdflatex、HTML経由ならweasyprint、ms出力ならgroff、typst出力ならtypstが選ばれます。 ここが日本語で引っかかる理由です。既定のpdflatexは日本語の文字を直接扱えません。フォントを指定する`CJKmainfont`を使う場合、公式マニュアルはxelatexならxeCJK、lualatexならluatexjaが必要だと明記しています。つまりオプションを足すだけでは足りず、LaTeX側に対応パッケージが入っていることが条件になります。エラーメッセージがLaTeXのものであれば、Pandocではなくディストリビューション側を疑ってください。 ``` # LuaLaTeX経由で日本語PDFを出力する pandoc spec.md -o spec.pdf --pdf-engine=lualatex -V CJKmainfont="Noto Serif CJK JP" # XeLaTeXを使う場合 pandoc spec.md -o spec.pdf --pdf-engine=xelatex -V CJKmainfont="Noto Serif CJK JP" ``` ### TeXを入れずに済ませる選択肢｜typst・weasyprintを指定した出力 LaTeX環境の導入がどうしても重い場合、PDFエンジンを差し替える方法も選択肢の一つです。weasyprintはHTMLとCSSを経由してPDFを作るため、Web側のスタイル資産をそのまま使えます。組版の指定をCSSで書けるぶん、見た目の調整はLaTeXよりも取り回しが楽な場面があります。 typstも指定できる選択肢です。判断基準は単純で、数式や相互参照が多い技術文書ならLaTeX系、Webの体裁に寄せたい配布資料ならweasyprintという分け方になります。両方を並行して維持すると、フォント指定が二重管理になるため、どちらかに寄せてください。 ``` # TeXを入れずHTML経由でPDFを出力する pandoc spec.md -o spec.pdf --pdf-engine=weasyprint --css=print.css ``` ## CIでドキュメントを自動生成する構成｜Dockerイメージとバージョン固定 手元で通った変換をCIへ移すと、エンジンやフォントの差で出力が変わります。公式が配布するDockerイメージを使い、タグを固定するのが定石です。 ### minimal・core・latex・extraの4イメージとタグ固定の考え方 [公式のdockerfilesリポジトリ](https://github.com/pandoc/dockerfiles)は4種類のイメージを配布しています。minimalは可能な限り小さく保った構成、coreは一般的な変換作業向けで追加ライブラリを含む構成、latexはcoreの上に基本的なLaTeX環境を載せた構成、extraはlatexにテンプレート・フィルタ・フォントを加えた構成です。PDFを出すならlatex以上、日本語フォントまで込みで揃えたいならextraが候補になります。 タグは固定してください。Docker Hubのpandoc/latexには、2026年9月8日更新で`3.11`、`3.11-alpine`、`3.11-debian`、`latest`が並んでいます。`latest`を指したままにすると、変換結果が変わった原因を版の差か原稿の差かで切り分けられなくなります。 ``` # Dockerイメージの版を固定して変換する docker run --rm --volume "$(pwd):/data" --user $(id -u):$(id -g) \ pandoc/latex:3.11 spec.md -o spec.pdf ``` ### 生成したPDFをアーティファクトとして残すワークフローの組み方 CIでの組み方は、コンテナにpandocイメージを指定し、変換ステップの後に生成物をアップロードする形が素直です。リポジトリへPDFをコミットして戻す構成は、差分が毎回バイナリで膨らむうえ、生成物と原稿の二重管理になります。成果物はアーティファクトとして残し、必要なときに取りに行くほうが運用が軽くなります。 保持期間や同名アーティファクトの扱いには制約があるため、設計時に確認しておいてください。[GitHub Actionsのアーティファクト｜受け渡しの設計と同名不可・保持期間の決め方](https://www.issoh.co.jp/tech/details/16951/)でその部分を整理しています。 ``` name: build-docs on: [push] jobs: pdf: runs-on: ubuntu-latest container: pandoc/latex:3.11 steps: - uses: actions/checkout@v4 - run: pandoc docs/spec.md -o spec.pdf --pdf-engine=lualatex -V CJKmainfont="Noto Serif CJK JP" - uses: actions/upload-artifact@v4 with: name: spec-pdf path: spec.pdf ``` アクションの版は自リポジトリの運用に合わせてください。コンテナ側でPDFエンジンとフォントが揃っていれば、変換ステップ自体は1行で済みます。 ## Pandocを採用しない場面｜デザイン指定の強い納品物と共同編集の要件 ここは立場を明確にします。Pandocを入れないほうが速い場面は実在し、無理に通すと工程が増えます。 ### Pandocを挟まないほうが速い3つの条件と、片道変換に限定する判断 次の3条件のいずれかに当たるなら、導入を見送ってください。第一に、納品物のレイアウトが確定していて、最終工程にWord上の手作業が必ず残る場合です。Pandocの出力をWordで直す運用は、原稿を直すたびに手作業をやり直すことを意味します。 第二に、執筆者が非エンジニアで、コマンドラインもGitも使わない体制の場合です。変換の前段にあるMarkdown運用が回らなければ、変換だけ自動化しても効果が出ません。第三に、docxを原本とした双方向の同期が要件になっている場合です。前述のとおり中間表現に載らない情報は落ちるため、往復は設計として成立しません。 逆に言えば、Markdownを原本と決められて、配布形式が複数あり、更新頻度が高い文書であれば導入する価値があります。この3点が揃っているかどうかだけで判断してください。 ### –lua-filterと–filterの使い分けと、書き始める前の損益分岐 標準の変換で足りない加工を補う方法は、フィルタによるASTの書き換えです。公式マニュアルは`--filter`をJSON形式でASTを受け渡す外部実行ファイル、`--lua-filter`をPandoc組み込みのLuaシステムを使うスクリプトと区別しています。仕様は[Luaフィルタのドキュメント](https://pandoc.org/lua-filters.html)にまとまっています。 書くかどうかの分岐はこうです。文字列の単純な置換で済むなら、変換前にテキスト処理で片づけたほうが早く終わります。見出しレベルの一括変更や画像パスの書き換えのように、構造を見ないと判定できない加工が出てきた時点でLuaフィルタへ移ってください。外部のAPIを叩く、既存のPythonライブラリを使うといった要件があるなら`--filter`側です。フィルタが3本を超えたあたりから保守対象になるため、そこまで来たらドキュメント生成の仕組み全体を設計し直す判断も選択肢に入ります。 ## よくある質問 Pandocの導入時に検索されることの多い質問を、公式ドキュメントの記述をもとに整理しました。 ### インストールしたのにpandocコマンドが見つからないときは？ PATHが通っていないケースがほとんどです。まずインストール方法を思い出してください。ZIPやtarballを展開して手動配置した場合、実行ファイルの置き場所を自分でPATHへ追加する必要があります。winget・Chocolatey・Homebrew・ディストロのパッケージから入れた場合は自動で通るため、シェルを開き直すだけで解決することがあります。`pandoc --version`が通るかどうかで切り分けてください。 ### HTMLやdocxは出るのにPDFだけエラーになるのはなぜですか？ PandocがPDFを自前で作らず、外部のPDFエンジンへ処理を渡しているためです。既定ではLaTeX経由でpdflatexが呼ばれるため、TeX環境が入っていないとその時点で止まります。WindowsならMiKTeX、LinuxならTeX Live、macOSならBasicTeXやTinyTexを入れてから再実行してください。エラー文面がLaTeXのものであれば、原因はPandoc側ではありません。 ### WordのファイルをMarkdownに変換できますか？ WordのファイルからMarkdownへの変換は可能です。`pandoc spec.docx -o spec.md`で逆方向の変換が走ります。ただし変更履歴・コメント・テキストボックス・複雑な段組みなど、内部の中間表現に対応する概念がない要素は落ちます。既存資産の初回移行として一度だけ通すのは有効ですが、docxとMarkdownを双方向で同期させる運用には向きません。移行後はMarkdownを原本に固定してください。 ### 日本語のフォントはどこで指定しますか？ `-V CJKmainfont="フォント名"`の形でテンプレート変数として渡します。ただしオプションだけでは足りません。公式マニュアルは、CJKmainfontを設定する場合にxelatexならxeCJK、lualatexならluatexjaが必要だと記載しています。エンジン指定と対応パッケージの導入をセットで行ってください。フォント名は環境に入っている実際の名前と一致させます。 ### CIで版が上がって出力が変わるのを防ぐには？ Dockerイメージのタグをバージョンまで含めて固定します。`pandoc/latex:latest`ではなく`pandoc/latex:3.11`のように指定すれば、実行時点で版が上がることはありません。Docker Hubのpandoc/latexには3.11・3.11-alpine・3.11-debianといったタグが揃っています。フォントやLaTeXパッケージもイメージ側に含めておくと、ローカルとCIで出力を揃えられます。 ## 関連記事 - [LaTeXとは？読み方・TeXとの違い・使い方を解説](https://www.issoh.co.jp/tech/details/9718/)：PDF出力で使う組版エンジン側の全体像です - [GitHub Actionsのアーティファクト｜受け渡しの設計と同名不可・保持期間の決め方](https://www.issoh.co.jp/tech/details/16951/)：生成したPDFをCIで受け渡す際の設計です - [Astroフレームワークとは？特徴と使い方・Next.jsとの使い分けを解説【2026年版】](https://www.issoh.co.jp/tech/details/15369/)：Markdown原稿からサイトを組む別経路です --- 出典: [Pandocの使い方｜Markdownからdocx・PDF変換の手順と日本語出力の詰まり方]()（株式会社一創）