[雑#1] Zenn記事をPandocでA5 PDF資料化メモ（数式・コード背景グレー対応）
[雑#1] Zenn記事をPandocでA5 PDF資料化メモ（数式・コード背景グレー対応）
Zennで、数式＋コード多めの記事を書いていて、元のmdファイルから、見た目の整ったPDF資料（A5サイズ、目次付き、コード背景グレー）に変換したい人向けの資料をメモとしてまとめてみました。ファイルの変換としては、mdファイルから、pdfファイルへの変換となります。
※ 本記事は Pandoc 3.8.3、MiKTeX-XeTeX 4.16 (MiKTeX 25.12)、Lua 5.4（2026年1月時点）を使用しています。
まず試す（最小構成）
pandoc your-article.md -o output.pdf \
--pdf-engine=xelatex \
-V CJKmainfont="Noto Sans JP" \
--toc
このPandocコマンドは、Markdown形式の文書（your-article.md）を、日本語対応のPDFファイル（output.pdf）に変換するためのものです。以下のような処理が行われます：
- PandocがMarkdownファイルを読み込み、LaTeX形式に変換します。
- XeLaTeXというLaTeXエンジンを使って、PDFを生成します。XeLaTeXは日本語や多言語に強く、フォント指定も柔軟です。
- CJKmainfont="Noto Sans JP" によって、日本語部分に「Noto Sans JP」フォントが使われます。これにより、PDF内の日本語が美しく表示されます。
- --toc オプションにより、Markdown内の見出し（# や ## など）をもとに自動で目次が作成され、PDFの先頭に挿入されます。
このコマンドは、Pandocを使って日本語のMarkdown文書を、目次付きの整ったPDFに変換したいときの基本形として、とてもよく使われる構成です。
テンプレートを使う場合と使わない場合
テンプレートを使う方法として、--template=custom_template.tex のような指定することにより、別のファイルを読み込んで指定する方法もあります。
| 項目 | テンプレートなし | テンプレートあり | 違い |
|---|---|---|---|
| 手軽さ | ✅ 試しやすい | ⚠️ 設定ファイルが必要 | - |
| 数式・日本語PDF | ✅ 可能 | ✅ 可能 | なし |
| 目次 | ✅ つけられる | ✅ つけられる | なし |
| コードフォント | デフォルト | 8pt（小さい） | ◆ |
| コード背景 | ❌ なし | ✅ グレー | ★ |
| A5サイズ・余白 | ⚠️ 毎回指定必要 | ✅ 設定済み | ◆ |
| 表の行間 | 標準 | 1.2倍 | ◆ |
テンプレートなしではできないこと:
- コードブロックに背景色をつける
- コードフォントを小さくする
- 表の行間を広げる
おすすめ: テンプレートを使う方（本記事の設定済み）
サンプルファイルのダウンロード
-
command.sh
PDF生成スクリプト。PATH設定後、pandocコマンドでsample.mdをA5サイズのPDFに変換します。テンプレート・日本語フォント・目次オプションを指定し、生成結果を確認し てファイルサイズを表示します。 -
custom_template.tex
Pandoc用LaTeXテンプレート。コードブロックに8ptフォント・グレー背景を適用し、 表の行間を1.2倍に設定します。\usepackage[table]{xcolor}とfvextraで背景色を実現 しています。 -
sample.md
量子化学計算入門の記事のサンプルであるMarkdown元ファイルです。全13要素（見出し・表・コード・数式・改ペ ージ等）を含み、各要素にHTMLコメントでアルファベットラベル（A-M）を付けています。記事との対応確認用です。
サンプルファイルのURL( command.sh, custom_template.tex, sample.md )
実行方法
方法1: コマンドを直接実行
cd articles/zenn/20260120_pandoc_01
pandoc sample.md -o sample.pdf \
--pdf-engine=xelatex \
--template=custom_template.tex \
-V CJKmainfont="Noto Sans JP" \
-V fontsize=12pt \
-V geometry:"paperwidth=14.8cm,paperheight=21cm,top=1.5cm,bottom=2cm,left=1.5cm,right=1.5cm" \
--toc --toc-depth=3
方法2: command.sh を実行
cd articles/zenn/20260120_pandoc_01
source ./command.sh
# または
bash command.sh
command.sh の内容（参考）:
#!/bin/bash
export PATH="/c/Users/hello/AppData/Local/Pandoc:/c/Users/hello/AppData/Local/Programs/MiKTeX/miktex/bin/x64:$PATH"
pandoc sample.md -o sample.pdf \
--pdf-engine=xelatex \
--template=custom_template.tex \
-V CJKmainfont="Noto Sans JP" \
-V fontsize=12pt \
-V geometry:"paperwidth=14.8cm,paperheight=21cm,top=1.5cm,bottom=2cm,left=1.5cm,right=1.5cm" \
--toc --toc-depth=3
セットアップ
必要なソフトウェア
| ソフトウェア | 役割 | インストール先 |
|---|---|---|
| MiKTeX | LaTeXディストリビューション | %LOCALAPPDATA%\Programs\MiKTeX\ |
| Pandoc | ドキュメントコンバータ | %LOCALAPPDATA%\Pandoc\ |
| Noto Sans JP | 日本語フォント | システムフォントにインストール |
PATH設定（.bashrc）
export PATH="/c/Users/$USER/AppData/Local/Pandoc:$PATH"
export PATH="/c/Users/$USER/AppData/Local/Programs/MiKTeX/miktex/bin/x64:$PATH"
source ~/.bashrc
改ページ・改行
| 目的 | Markdown記法 | PDF出力 |
|---|---|---|
| 段落改行 | 空行 | 有効 |
| 強制改行 | 行末スペース2つ | 有効 |
| 強制改行 | <br> |
有効 |
| 改ページ | \newpage |
有効（xelatex） |
改ページを使ってページを切り替えています。Markdownの中に \newpage をLaTeXとして解釈される（＝--pdf-engine=xelatexなどを指定）。
改ページサンプル:
---
title: タイトル
---
\newpage
## 第1章
本文。
\newpage
## 第2章
注意点:
- YAMLの
titleを使う場合、Markdownの#見出しは重複するため削除する -
\newpageはYAMLブロック（---）の直後に配置する -
#見出しだけを使う場合は、その後に\newpageを配置する
実践的なコマンド（A5・コード背景グレー）
pandoc your-article.md -o output.pdf \
--pdf-engine=xelatex \
--template=custom_template.tex \
-V CJKmainfont="Noto Sans JP" \
-V fontsize=12pt \
-V geometry:"paperwidth=14.8cm,paperheight=21cm,top=1.5cm,bottom=2cm,left=1.5cm,right=1.5cm" \
--toc --toc-depth=3
オプション解説
| オプション | 説明 |
|---|---|
--pdf-engine=xelatex |
日本語対応・\newpage有効 |
--template=custom_template.tex |
8ptコード・グレー背景設定 |
-V CJKmainfont="Noto Sans JP" |
日本語フォント |
-V geometry:... |
A5用紙・余白設定 |
--toc |
目次有効 |
注意点：Zenn記法の前処理
| Zenn記法 | 処理 | 理由 |
|---|---|---|
:::message :::
|
> に置換 |
Pandoc非対応 |
:::alert :::
|
> に置換 |
同上 |
----（4つ以上） |
--- に修正 |
3つが標準 |
---（水平線） |
*** に置換 |
YAML終了マーカーと競合 |
:::details :::
|
削除またはHTMLタグ | 折りたたみ要素 |
罠：バックスラッシュの一括変換禁止
数式変換で問題がでたので、使わない方が無難です。
# ❌ 絶対に実行禁止
sed -i 's|\\|/|g' file.md # \hat{H} が /hat{H} に壊れる
確認コマンド:
grep -n "^:::" article.md
その他の注意点
| 記号 | 問題 | 対処 |
|---|---|---|
_ |
強調記号と競合 |
\_ でエスケープ |
< > |
HTMLタグと解釈 |
\< \> でエスケープ |
| |
テーブル内でエスケープが必要 |
\| で記述 |
--- |
YAML終了マーカーと競合 |
*** を使用 |
サポートしているMarkdown要素
※ アルファベット（A-M）は本記事でsample.mdと対応させるために独自の設定したラベル付けです。
| 要素 | 対応 | sample.md参照 |
|---|---|---|
A. 見出し #, ##, ###
|
✅ | 行8, 11 |
| B. 表 | ✅ | 行48-52, 85-89 |
| C. コードブロック | ✅ | 行40-44, 57-76 |
D. 水平線 ***
|
✅ | 行97 |
E. 数式 $...$, $$...$$
|
✅ | 行14-16, 20, 25-27 |
F. 箇条書き -
|
✅ | 行34-36, 103-106 |
G. 引用 >
|
✅ | 行80 |
H. リンク [text](url)
|
✅ | 行94-95 |
| I. LaTeX参考文献 | ⚠️ | 要追加パッケージ |
| J. サブタイトル | ✅ | 行3（YAML） |
| K. 要約 | ✅ | 行4（YAML） |
| L. 図目次/表目次 | ❌ | 要LaTeX拡張 |
M. 改ページ \newpage
|
✅ | 行7, 105 |
アルファベットとsample.mdコメントの対応:
- sample.md内の
<!-- A: 見出し (#) -->等のHTMLコメントで、各要素の使用箇所を示しています - J・K（YAMLメタデータ）のみ、フロントマター内のためsample.mdにコメントなし
カスタムテンプレート（custom_template.tex）
% 画像サイズ（デフォルト90%）
\setkeys{Gin}{width=0.9\linewidth}
% 色と表のサポート（コード背景色に必須）
\usepackage[table]{xcolor}
% コードブロック（8pt + グレー背景）
\usepackage{fvextra}
\definecolor{codegray}{gray}{0.90}
% header-includes の後に配置
\RecustomVerbatimEnvironment{verbatim}{Verbatim}{
breaklines=true, % 長い行を折り返し
fontsize=\fontsize{8pt}{10pt}\selectfont,
bgcolor=codegray, % 背景色（fillcolorではなくbgcolor）
frame=lines, % 上下枠線
framesep=2.5mm, % 余白
rulecolor=\color{gray!40}, % 枠線色
}
% 表の行間（1.2倍）
\usepackage{array}
\renewcommand{\arraystretch}{1.2}
設定内容:
- 画像サイズ: 90%
- コードフォント: 8pt
- コード背景: グレー(#90)
- 表の行間: 1.2倍
注意点:
-
bgcolorを使用（fillcolorでは動作しない） -
\usepackage[table]{xcolor}が必須 -
\RecustomVerbatimEnvironmentはheader-includesの後に配置
参考文献
Pandoc関連
商用利用について
ライセンス: GPL-2.0-or-later
注意: PandocはGPLライセンスのため、再配布や組み込みには注意が必要です。商用利用前に必ず公式情報源で最新の条件を確認してください。
バージョン情報（pandoc -v で確認）:
pandoc 3.8.3
Copyright (C) 2006-2025 John MacFarlane
Web: https://pandoc.org
Discussion