render-pdf-doc

Render-PDF-Doc スキル

このスキルは、raw pandoc + xelatex を使ったレイアウト調整（CJK フォント、表の列幅）だけを扱います。tbl-colwidths で PDF のリグレッションが報告されている Quarto（issue 6089/9200）は使用しません。対象外：参考文献付きの原稿（/manage-refs scripts/render_pandoc.sh）、機関指定の .docx フォーム（/fill-protocol）、ICMJE COI フォーム（/fill-icmje-coi）、図表や PPTX（/make-figures、/present-paper）。

依存関係

ラッパーの実行には Python 3 が必要です。フォントファイルのカバレッジ確認には FontTools を任意で使用できます（python3 -m pip install fonttools）。

# macOS
brew install pandoc
brew install --cask mactex-no-gui          # xelatex + xeCJK (~5 GB)

# Linux
sudo apt-get install pandoc texlive-xetex texlive-lang-cjk fonts-noto-cjk

# Windows (PowerShell) — run in Git Bash afterwards
winget install --id JohnMacFarlane.Pandoc
winget install --id MiKTeX.MiKTeX          # xelatex; installs missing LaTeX packages on demand
# No CJK font download needed: Malgun Gothic ships with Windows 7+ and is the default here.

検出：

bash scripts/check_deps.sh

Windows / Git Bash では、MiKTeX の bin ディレクトリ （%LOCALAPPDATA%\Programs\MiKTeX\miktex\bin\x64）が PATH に含まれていないことがよくあります。check_deps.sh と render_pdf.sh はどちらもこのディレクトリを検索します。それでも xelatex が [MISS] と表示される場合は、このディレクトリを PATH に追加してください。

ワークフロー

ステップ 1 — frontmatter 付きの Markdown を作成する

---
title: "Paper 2 Calibration Anchor — Q&A Grid"
author: "<Author Group>"
date: "2026-05-01"
mainfont: "Apple SD Gothic Neo"        # macOS default
CJKmainfont: "Apple SD Gothic Neo"
geometry: "margin=0.85in"
fontsize: 11pt
linestretch: 1.25
colorlinks: true
---

• mainfont と CJKmainfont の両方を設定してください。CJKmainfont がないと、ハングルの表示に Times New Roman が使われ、グリフが崩れたり空白になったりします。Linux/CI では Noto Sans CJK KR、Windows では Malgun Gothic を使用してください。フィールドが指定されていない場合、レンダリングスクリプトが OS ごとのデフォルトを自動検出します。
• 表内のすべての数値は、元の CSV または分析出力から読み取ってください。文章中の数値を転記したり、以前のドラフトの数値をそのまま引き継いだりしないでください。v3 で正しい表だからといって、v4 でも正しいとは限りません。
• 回覧用 PDF に変更履歴、内部バージョン番号（例：v3.2.2）、PI の帰属情報を含めないでください。それらは別の回覧ファイルまたは補足資料に記載してください。受領した一次資料（共著者から送られた .docx または .eml）は、独立した成果物として変更せずに保管してください。PDF は派生物であり、次のラウンドでは一次資料との差分を確認します。その一次資料が共同研究者によって AI で作成された場合は、PDF に反映する前に、記載されたすべての数値、分母、著者年を元論文または分析出力から再確認してください。

ステップ 2 — 列幅を推定する

パイプテーブルの列幅を均等にしてはいけません。短いラベルだけを含む列にもデータ列と同じ幅が割り当てられ、データ列が窮屈になるためです。内容に応じて幅を調整します。

python3 scripts/infer_colwidths.py input.md > input.colwidths.md

各パイプテーブルについて、列ごとの表示幅を max(len(header), max(len(cell)))（CJK は 2 セル、ASCII は 1 セル）で計算し、区切り行のダッシュ数を比例配分で書き換えます。幅を手動で設定するには、区切りのダッシュを自分で記述し、--infer-colwidths を指定せずにレンダリングしてください。

ステップ 3 — レンダリング

bash scripts/render_pdf.sh -i input.colwidths.md -o output.pdf

または一括実行：

bash scripts/render_pdf.sh -i input.md -o output.pdf --infer-colwidths

フロントマターはラッパーのデフォルトより優先されます。--font / --cjk-font も同様です。 フィールドが指定されていない場合は、ラッパーまたは OS のデフォルトが使われます。これは geometry、fontsize、linestretch、colorlinks（false を含む）にも適用されます。明示的な pandoc の -V / -M 引数を -- の後に指定した場合は、フロントマターより優先されます。たとえば、 -- -V fontsize=10pt です。ラッパーがログに記録するのはフォントのフォールバックであり、最終的なフォントではありません。

標準の article クラスが対応するのは 10pt、11pt、12pt のみで、それ以外のサイズは警告なく 無視されます。有効な fontsize がこれら以外で、documentclass が設定されていない場合、ラッパーは KOMA-Script の scrartcl（pandoc のドキュメントで説明されている方法）に切り替えます。また、 classoption を指定していない場合は classoption: fontsize=<size> を追加します（KOMA で小数のサイズ、 たとえば 8.5pt を読み取るには、この方法が必要です）。切り替えはログに記録されます。これを上書きするには、 documentclass を自分で設定してください。

xeCJK のデフォルトは中国語向けに設定されており、曲線引用符や en/em ダッシュの後のスペースを削除し、 ラテン文字または数字とハングルが隣り合う箇所にスペースを挿入します。

typed:    “no difference” and      AI를 썼다    3개
printed:  “no difference”and       AI 를 썼다   3 개

ラッパーは両方を無効にし（scripts/xecjk_korean.tex）、PDF では入力したスペースが保持されるようにします。このファイルは header-includes に追加されます。-- の後に -H を渡した場合（header-includes が置き換えられます）は、 このファイルが追加の -H として指定されます。別の方法で指定したヘッダー（include-in-header を含む --defaults ファイル、または -V header-includes=...）は追加された設定より優先されるため、これらと併せて -H "${CLAUDE_SKILL_DIR}/scripts/xecjk_korean.tex" を渡してください。--xecjk-defaults を指定すると、 中国語や日本語のテキストなどで xeCJK 独自のスペース処理が維持されます。 pdftotext -layout out.pdf - | grep -cE '[”’][A-Za-z]' で確認できます（所有格を除いて 0）。

ステップ 3.5 — 科学記号と CJK グリフのスキャン（レンダリング前）

xelatex はグリフが欠落していても正常に終了することがあります。render_pdf.sh は pandoc が中継する Missing character 警告を数えます。警告がある場合、グリフごとに一覧（コードポイント、件数、フォント）を表示し、 終了コード 4 で終了します。PDF は出力されますが、不完全です。警告は pandoc の JSON --log から読み取ります （-- の後に渡したログがあれば、それを使用します）。そのため、パススルーの --quiet を指定しても警告は隠れません。 --allow-missing-glyphs を指定すると、同じ一覧を表示して終了コード 0 で終了します。学術論文の Markdown には、 デフォルトのラテン文字フォントでは表示できないグリフが頻繁に含まれています。たとえば、遷移矢印（→ ↑ ↓）、 数学演算子（− ≤ ≥ ± √ ∪ × ≈ ≠）、統計で使われるギリシャ文字（κ μ σ β）、箇条書き記号やマーク（• ★ ✓）、 CJK などです。出力前に見落としを検出できるよう、まずソースをスキャンしてください。

python3 scripts/scan_glyph_coverage.py input.md --strict
# real cmap check when you have the font file + fonttools:
python3 scripts/scan_glyph_coverage.py input.md --font "/path/to/body.otf" --strict
# TTC/OTC collections require the zero-based face index used by the renderer:
python3 scripts/scan_glyph_coverage.py input.md --font "/path/to/body.ttc" --font-index 0 --strict --json glyphs.json

--font を指定しない場合、リスクのあるグリフをクラスごとに分類して参考情報として表示します。--font と fonttools を指定した場合は、5 つのクラスに限らず、そのフォントに描画させるソース内の ASCII 以外の文字を すべて確認します。そのため、°、µ、²、‰、∞、– も対象です（BOM やゼロ幅接合子などの書式文字と、 pandoc が ASCII の TeX として出力する改行なしスペースや … は検索されません）。コレクション内の複数のフェイスにまたがって 対応状況をまとめることはありません。レンダリングされたフォントに一致するフェイスを選んでください（インデックスと PostScript 名はレポートに記載されます）。依存関係の欠落、読み取れないフォント、フェイスの選択漏れ、無効なインデックスは、 理由とともに font_check に font_checked: false として報告されます。その場合、missing_in_font の一覧が空でも 対応状況が未検証であることを意味し、完全に対応しているわけではありません。デフォルトモードの終了コードは 0 です。 --strict は、リスクのあるグリフが未検証または欠落している場合に終了コード 1 で終了します（ASCII のみの入力では 終了コード 0 です）。このスキャンでは、シェーピング、フォールバックフォント、数式フォント、最終的な PDF のグリフは検証されません。

リスクのあるグリフが含まれている場合は、mainfont / CJKmainfont が対応していることを確認してください。 Apple SD Gothic Neo / Noto Sans CJK などの CJK 対応フォントは、通常、矢印やハングルに対応していますが、 真のマイナス記号 − U+2212 や ★ が欠落していることもあります。DOCX が正式な成果物であり、PDF は利便性のための コピーです。ドキュメントに必要なグリフが PDF のレンダリングで欠落しないようにしてください。

ステップ 4 — 見た目を確認する

PDF を開いて、次の点を確認します。

• 1 列目のラベルが 1 行に収まり、データ列に十分な幅があること。
• 韓国語の文字が正しく表示されていること（Times New Roman にフォールバックしている場合は、CJKmainfont が適用されていません）。
• 科学記号（矢印、−、≤、±、√）が欠けていないこと — ステップ 3.5 のスキャンで候補が検出されます。
• 変更履歴や内部バージョン番号が表示されていないこと。

レンダリングがまだ正しく見えない場合は references/known_pitfalls.md（em ダッシュのはみ出し、CJKmainfont 使用時のスマートクォート、セル内の |）を参照し、韓国語のフロントマターやフォントのパターンについては references/pandoc_korean_cheatsheet.md を参照してください。

テンプレート

templates/ 内のスターターマークダウン（デフォルトは英語。各ファイルには韓国語版の *_ko.md も付属します）には、次のプレースホルダーがあります。

• anchor-doc.md — Q&A グリッド
• proposal-cover.md — 研究提案書の表紙
• briefing-handout.md — 会議用ブリーフ（1 ページ）
• reference-table.md — 比較表形式