pandoc プログラム仕様
Pandoc専用：MarkdownのWord/PowerPoint/HTML変換とテンプレート生成。
このモジュールは、Pandocツールを利用してMarkdownファイルを様々な形式（Word, PowerPoint, HTML）に変換するためのユーティリティを提供します。 また、Pandocで使用するテンプレートファイルの生成機能も備えています。
AI処理は一切ありません（tkai_lib不要）
使用例:
# テンプレート生成 python pandoc_convert.py --make_template docx --template template_textbook.docx python pandoc_convert.py --make_template pptx --template template_slide.pptx
# 変換 python pandoc_convert.py --convert docx --infile lecture_textbook.md --template template_textbook.docx python pandoc_convert.py --convert pptx --infile lecture_slide.md --template template_slide.pptx python pandoc_convert.py --convert html --infile lecture_textbook.md --mathml python pandoc_convert.py --convert html --infile lecture_textbook.md --css custom_style.css
- 関連リンク:
- converter.pandoc.convert_md(infile_md: str, target: str, pandoc_path: str, outfile: str = None, template: str = None, toc: bool = False, css: str = None, mathml: bool = False, no_yaml: bool = False, verbose: bool = False, smart_conversion: int = 0) bool[ソース]
Markdownファイルをdocx、pptx、またはhtml形式に変換するライブラリAPI。
- 詳細説明:
この関数は、コマンドライン引数ではなくPythonの関数呼び出しとしてPandocの変換機能を提供します。 指定されたMarkdownファイルを読み込み、correct_markdown_pandoc_error で前処理を行った後、 convert_with_pandoc を呼び出して実際の変換を実行します。 修正されたMarkdownは一時ファイルに書き出され、変換後にPandocによって使用されます。
- パラメータ:
infile_md -- str: 入力Markdownファイルのパス。
target -- str: 変換ターゲットフォーマット ('docx', 'pptx', 'html')。
pandoc_path -- str: Pandoc実行ファイルのパス。
outfile -- str | None: 出力ファイルのパス。指定しない場合、入力ファイル名から推測される。デフォルトはNone。
template -- str | None: 参照テンプレートファイルのパス。docx/pptx変換時に使用。デフォルトはNone。
toc -- bool: 目次を生成するかどうか。デフォルトはFalse。
css -- str | None: HTML変換時に使用するカスタムCSSファイルのパス。デフォルトはNone。
mathml -- bool: HTML変換時にMathMLを使って数式を表示するかどうか。デフォルトはFalse。
no_yaml -- bool: YAMLフロントマターをmarkdown-yaml_metadata_blockとして解釈しないかどうか。デフォルトはFalse。
verbose -- bool: 詳細出力を有効にするかどうか。デフォルトはFalse。
smart_conversion -- int: 自動変換 (--を-に変換するなど) を行うかどうか (0: 無効, 1: 有効)。デフォルトは0。
- 戻り値:
bool: 変換が成功した場合はTrue。
- 例外:
RuntimeError -- ファイルの読み込みに失敗した場合。
- converter.pandoc.convert_with_pandoc(pandoc_path: str, target: str, infile_md: str, outfile: str, template: str = None, css: str = None, no_yaml: bool = False, args: Namespace = None)[ソース]
Pandocを使ってMarkdownファイルを指定された形式に変換する。
- 詳細説明:
この関数は、入力Markdownファイルを指定されたターゲット形式（docx, pptx, html）に変換するために、 Pandocコマンドラインツールを呼び出します。 出力ファイルパスの決定、参照テンプレート（docx/pptx）、カスタムCSS（html）、 目次生成、MathMLサポート、YAMLフロントマターの処理など、様々な変換オプションをサポートします。 HTML変換の場合、correct_html を呼び出してMathJax対応の最終処理を行います。
- パラメータ:
pandoc_path -- str: Pandoc実行ファイルのパス。
target -- str: 変換ターゲットフォーマット ('docx', 'pptx', 'html')。
infile_md -- str: 入力Markdownファイルのパス。
outfile -- str: 出力ファイルのパス。指定しない場合、入力ファイル名から推測される。
template -- str | None: 参照テンプレートファイルのパス。docx/pptx変換時に使用。デフォルトはNone。
css -- str | None: HTML変換時に使用するカスタムCSSファイルのパス。デフォルトはNone。
no_yaml -- bool: YAMLフロントマターをmarkdown-yaml_metadata_blockとして解釈するかどうか。 Trueの場合、PandocはYAMLブロックを特殊なものとして扱わない。デフォルトはFalse。
args -- argparse.Namespace: parse_args によって解析された全ての引数オブジェクト。 toc, mathml, verbose, smart_conversion, convert などのフラグを含む。
- converter.pandoc.correct_html(outfile: str)[ソース]
Pandocが生成したHTMLファイルをMathJax対応の完全なHTMLドキュメントに修正する。
- 詳細説明:
Pandocが --mathml オプションなしで生成したHTMLは、MathJaxを読み込むためのスクリプトや HTMLヘッダー/フッターが欠けている場合があります。この関数は、指定されたHTMLファイルを読み込み、 MathJax CDNスクリプトを含むHTML5の基本的な構造（<!DOCTYPE html>, <html>, <head>, <body>）でラップし、 再保存することで、ブラウザで正しく表示されるようにします。
- パラメータ:
outfile -- str: 修正対象のHTMLファイルのパス。
- converter.pandoc.correct_markdown_pandoc_error(md_text: str, base_dir: Path = None) str[ソース]
Pandocがエラーを出す典型的なMarkdownの記述を自動修正する。
- 詳細説明:
この関数は、Pandocでの変換時に問題を引き起こしやすいMarkdownのパターンを検出し、修正します。 主な修正内容は以下の通りです。 - YAMLフロントマターの安全化: Markdownの冒頭にある`---`ブロックがYAMLとして不正な場合、
Pandocが誤ってYAMLと認識しないよう、その前後に空行を追加して無効化します。 有効なYAMLフロントマターは変更しません。
水平線 (`---`) の安全化: YAMLフロントマター以外の単独の`---`が水平線として機能する場合、 その前後に空行を追加して、他の要素との境界を明確にし、Pandocの解釈ミスを防ぎます。
存在しない画像・リンクの無害化: `base_dir`が指定されている場合、Markdown内の画像やリンクが 示すファイルパスが実際に存在しない場合に、Pandocがエラーを出すのを防ぐため、 該当するMarkdownの記述をバッククォートで囲み、コードとして扱うように修正します。
ブロック数式 `$$ inline $$` の正規化: Pandocが正しく解釈できるよう、 $$ 数式 $$ の形式で書かれたインライン風のブロック数式を、 複数行のブロック数式形式 `$$
数式 $$` に正規化します。
生成AIが生成しがちな数式記述の変換: [ ... ] や ( ... ) といったTeX/LaTeX形式の数式記述を、 Pandocが確実に読める `$$
... $$` のブロック形式に変換します。
- param md_text:
str: 修正対象のMarkdownテキスト。
- param base_dir:
Path | None: 画像などの相対パスを解決するためのベースディレクトリ。 指定しない場合、ファイル存在チェックは行われません。デフォルトはNone。
- returns:
str: 修正されたMarkdownテキスト。
- converter.pandoc.extract_yaml_front_matter(md_text: str)[ソース]
Markdownテキストの先頭からYAMLフロントマターを抽出する。
- 詳細説明:
Markdownファイルの冒頭に `---
<YAML内容> ---` の形式で記述されたYAMLフロントマターを正規表現で検索し、
その内容を文字列として返します。見つからない場合はNoneを返します。
- param md_text:
str: Markdown形式のテキスト。
- returns:
str | None: 抽出されたYAMLフロントマターの文字列。見つからない場合はNone。
- converter.pandoc.find_pandoc() str | None[ソース]
pandoc 実行ファイルのパスを探す。
- 詳細説明:
以下の優先順位でpandoc実行ファイルを探索します。 1. 環境変数 pandoc_path で指定されたパス。 2. 環境変数 tkProg_path に基づく既定の配置パス。
Windows: {tkProg_path}/tkApp_Win/pandoc/pandoc.exe
Linux/macOS: {tkProg_path}/tkApp_Linux/pandoc/pandoc
3. システムの PATH 環境変数に登録されているパス。 いずれの場所でも見つからなかった場合は None を返します。
- 戻り値:
str | None: pandoc実行ファイルのパス。見つからない場合はNone。
- converter.pandoc.find_template(template_path: str) str | None[ソース]
テンプレートファイルのパスを解決する。
- 詳細説明:
与えられた template_path を以下の順序で探し、最初に見つかったファイルのフルパスを返します。 1. スクリプトが実行されているカレントディレクトリ。 2. このスクリプトファイルが存在するディレクトリ。 どの場所でもファイルが見つからない場合は、template_path をそのまま返します。
- パラメータ:
template_path -- str: テンプレートファイルのパスまたはファイル名。
- 戻り値:
str | None: 見つかったテンプレートファイルのフルパス、またはファイルが見つからない場合は元のパス。
- converter.pandoc.is_valid_yaml(yaml_text: str) bool[ソース]
与えられた文字列が有効なYAML形式であるかを判定する。
- 詳細説明:
yaml.safe_load を使用して文字列をパースを試みます。 パース中に例外が発生しなければ有効なYAMLと判断しTrueを返します。 それ以外の場合はFalseを返します。
- パラメータ:
yaml_text -- str: YAML形式であるかを確認する文字列。
- 戻り値:
bool: 有効なYAMLであればTrue、そうでなければFalse。
- converter.pandoc.main()[ソース]
スクリプトのメインエントリポイント。
- 詳細説明:
コマンドライン引数を解析し、それに基づいてPandoc関連の操作（テンプレート生成またはファイル変換）を実行します。 Pandoc実行ファイルの存在チェックや、必要な引数が指定されているかの検証も行います。 処理が完了した後、またはエラーが発生した場合、terminate() 関数を呼び出してプログラムを終了します。
- 戻り値:
None
- converter.pandoc.make_pandoc_template(pandoc_path: str, fmt: str, template_file: str)[ソース]
Pandocのデフォルトテンプレートファイルを生成する。
- 詳細説明:
指定されたフォーマット（docxまたはpptx）に対応するPandocのデフォルト参照ドキュメントを --print-default-data-file オプションを使用して出力します。 生成されたファイルは、ユーザーがカスタムスタイルを定義するためのベースとして利用できます。
- パラメータ:
pandoc_path -- str: Pandoc実行ファイルのパス。
fmt -- str: 生成するテンプレートのフォーマット ('docx'または'pptx')。
template_file -- str: 出力するテンプレートファイルのパス。
- converter.pandoc.parse_args()[ソース]
コマンドライン引数を解析する。
- 詳細説明:
argparse モジュールを使用して、Pandocユーティリティのコマンドライン引数を定義し、解析します。 Pandoc実行ファイルのパス、入力/出力ファイル、テンプレート、変換形式、HTML/CSSオプション、 テンプレート生成オプションなどをサポートします。また、find_template を使ってテンプレートパスを解決します。
- 戻り値:
tuple[argparse.ArgumentParser, argparse.Namespace]: パーサーオブジェクトと解析された引数オブジェクトのタプル。
- converter.pandoc.read_text_with_chardet(path: str) str | None[ソース]
ファイルの文字コードを自動推定し、テキストとして読み込む。
- 詳細説明:
まずファイルをバイナリモードで読み込み、chardet ライブラリを使用して文字コードを推定します。 推定された文字コードでファイルをデコードし、その内容を文字列として返します。 推定に失敗した場合やデコードエラーが発生した場合は、エラーメッセージを出力しNoneを返します。 推定されたエンコーディングがNoneの場合、またはデコードエラーが発生した場合は、'utf-8' を試行します。
- パラメータ:
path -- str: 読み込むファイルのパス。
- 戻り値:
str | None: ファイルの内容を文字列として返す。ファイルの読み込みに失敗した場合はNone。