Pandoc

1 概要

Pandoc は「ドキュメント変換のスイスアーミーナイフ」と呼ばれる汎用ドキュメント変換ツールです。Markdown・HTML・LaTeX・docx・PDF など多数のフォーマット間で変換ができます。カスタムテンプレートやフィルタ (Lua スクリプト) を使用して出力をカスタマイズすることも可能です。

このリポジトリの docsfw/ サブモジュールが Pandoc を使用した Markdown から HTML/docx への変換フレームワークを提供しています。Doxygen → Doxybook2 → Markdown という流れで生成された API ドキュメントを、Pandoc を使って最終的な HTML や Word ドキュメントに変換します。PlantUML 図の統合や日本語ドキュメントの対応も含まれています。

docsfw/bin/ のスクリプトが Pandoc の実行をラップしており、docsfw/styles/ のカスタムスタイルが適用されます。

2 習得目標

• pandoc input.md -o output.html で基本的な変換ができる
• --template オプションでカスタムテンプレートを適用できる
• --css オプションでスタイルシートを指定できる
• pandoc input.md -o output.docx で Word ドキュメントを生成できる
• --lua-filter オプションで Lua フィルタを適用できる
• Pandoc Markdown の拡張記法 (メタデータブロックなど) を理解できる

3 学習マテリアル

3.1 公式ドキュメント

• Pandoc 公式サイト - Pandoc のホームページ (英語)
• Pandoc ユーザーガイド - 完全なコマンドラインリファレンス (英語)
  • オプション一覧 - 全オプションの説明
  • テンプレート - カスタムテンプレートの書き方
  • Lua フィルタ - 変換処理のカスタマイズ

4 このリポジトリとの関連

4.1 使用箇所 (具体的なファイル・コマンド)

ドキュメント変換の流れ:

C ソースコード (Doxygen コメント)
    ↓ doxygen
XML ファイル (xml/)
    ↓ doxybook2
Markdown (docs-src/doxybook2/)
    ↓ pandoc (docsfw/)
HTML / docx (docs/ja/html/ など)

docsfw/ の構成:

docsfw/
+-- bin/        # Pandoc 実行スクリプト
+-- lib/        # フィルタ・変換ライブラリ (Lua フィルタなど)
+-- styles/     # カスタム CSS・Word スタイル

基本的な Pandoc コマンド (手動実行例):

pandoc docs-src/testing-tutorial.md \
    -o docs/ja/html/testing-tutorial.html \
    --template docsfw/templates/html.html \
    --css docsfw/styles/style.css

pandoc docs-src/testing-tutorial.md \
    -o testing-tutorial.docx \
    --reference-doc docsfw/styles/reference.docx

4.2 関連ドキュメント

• Markdown(スキルガイド) - Pandoc の入力となる Markdown の基礎
• Doxygen(スキルガイド) - Pandoc の前段となるドキュメント生成
• PlantUML(スキルガイド) - Pandoc と統合して使う図表ツール