document-converter

ドキュメント変換

概要

元の形式が許す限り構造を維持しながら、一般的なドキュメント形式やデータ形式を変換する必要がある場合に、このスキルを使用します。付属の CLI は、Markdown、HTML、CSV、JSON、YAML、TOML、プレーンテキスト、Excel、PDF 間の軽量なローカル変換に対応しています。

基本的な変換には Python 標準ライブラリを使用します。JSON、CSV、HTML の解析、Markdown のヒューリスティック処理、tomllib による TOML の読み込み、独自の TOML／YAML 出力処理が含まれます。PDF の出力には pandoc、Excel の読み込みには openpyxl を使用します。これらの変換を行う場合は、両方とも依存関係として必要です。依存関係が不足している場合は、トレースバックを表示して失敗するのではなく、明確なインストール方法を示してツールを終了します。

変換マトリクス

変換元	変換先	コマンド形式	依存関係	備考
Markdown	HTML	--from markdown --to html	標準ライブラリ	見出し、段落、リスト、フェンス付きコード、太字／斜体／コード、リンクに対応します。
HTML	Markdown	--from html --to markdown	標準ライブラリ	一般的なブロック／インラインタグに対応します。複雑な CSS／レイアウトは破棄されます。
HTML	テキスト	--from html --to text	標準ライブラリ	タグを除去し、エンティティをデコードして、段落／リストの改行を維持します。
CSV	JSON	--from csv --to json	標準ライブラリ	ヘッダー行がオブジェクトのキーになり、値は文字列のままです。
JSON	CSV	--from json --to csv	標準ライブラリ	ネストしたオブジェクトをドット記法でフラット化します。配列は JSON 文字列になります。
CSV	Markdown	--from csv --to markdown	標準ライブラリ	GitHub スタイルのパイプ区切りテーブルを生成します。
Markdown	CSV	--from markdown --to csv	標準ライブラリ	最初のパイプテーブルを読み込みます。
YAML	JSON	--from yaml --to json	標準ライブラリの代替処理、PyYAML は任意	PyYAML がない場合は、基本的な YAML のみ対応します。
JSON	YAML	--from json --to yaml	標準ライブラリ	2 スペースの YAML を出力します。アンカーには対応しません。
YAML	TOML	--from yaml --to toml	標準ライブラリの代替処理、PyYAML は任意	単一の YAML ドキュメントのみ対応します。TOML と互換性のある値に限られます。
TOML	YAML	--from toml --to yaml	標準ライブラリ	TOML テーブルはネストした YAML マッピングになります。
TOML	JSON	--from toml --to json	Python 3.11 以降の tomllib	TOML の日付／時刻は JSON では文字列になります。
JSON	TOML	--from json --to toml	標準ライブラリ	文字列、数値、ブール値、配列、ネストしたテーブルに対応します。
XLSX	CSV	--from xlsx --to csv	openpyxl	最初のワークシートのみを読み込みます。
Markdown	PDF	--from markdown --to pdf	pandoc	PDF は出力専用です。--output が必要です。

変換ごとの制限とデータ損失のリスクについては、references/conversion-matrix.md を参照してください。

クイックスタート

スキルのディレクトリから実行するか、スクリプトをパスで指定して呼び出します。

python scripts/convert.py --input notes.md --from markdown --to html --output notes.html

--from を省略した場合、形式は入力ファイルの拡張子から自動検出されます。

python scripts/convert.py --input notes.md --to html --output notes.html

対応している各変換の例：

# Markdown ↔ HTML
python scripts/convert.py --input page.md --to html --output page.html
python scripts/convert.py --input page.html --to markdown --output page.md

# HTML → plain text
python scripts/convert.py --input page.html --to text --output page.txt

# CSV ↔ JSON
python scripts/convert.py --input people.csv --to json --output people.json
python scripts/convert.py --input records.json --to csv --output records.csv

# CSV ↔ Markdown table
python scripts/convert.py --input people.csv --to markdown --output people-table.md
python scripts/convert.py --input people-table.md --to csv --output people.csv

# JSON ↔ YAML
python scripts/convert.py --input config.json --to yaml --output config.yaml
python scripts/convert.py --input config.yaml --to json --output config.json

# YAML ↔ TOML
python scripts/convert.py --input config.yaml --to toml --output config.toml
python scripts/convert.py --input config.toml --to yaml --output config.yaml

# JSON ↔ TOML
python scripts/convert.py --input config.json --to toml --output config.toml
python scripts/convert.py --input config.toml --to json --output config.json

# Excel → CSV, first sheet only; requires openpyxl
python scripts/convert.py --input workbook.xlsx --to csv --output sheet.csv

# Markdown → PDF; requires pandoc
python scripts/convert.py --input report.md --to pdf --output report.pdf

テキスト形式で --output を省略した場合、変換後の内容は標準出力に書き込まれます。

エッジケースの処理

• ネストされた JSON→CSV のフラット化： ネストされたオブジェクトはドット記法でフラット化されます。たとえば、{"user": {"name": "Ada"}} は user.name 列になります。CSV にはネストを表す標準機能がないため、リストやスカラー値以外のネストされた値はコンパクトな JSON 文字列としてシリアライズされます。
• CSV での型情報の喪失： CSV の値は文字列です。元の数値、ブール値、日付は、ソースで明示的にエンコードされ、後続の処理で型が再設定されない限り、CSV→JSON→CSV の往復変換では復元できません。
• HTML エンティティのデコード： HTML→Markdown と HTML→テキストでは、&、 、数値文字参照などのエンティティがデコードされます。空白は正規化され、ブラウザーでの正確なレイアウトは保持されません。
• YAML のサポート： PyYAML がインストールされている場合は使用されます。インストールされていない場合は、一般的なブロックスタイルのマッピング、リスト、ネストされた辞書、文字列、数値、ブール値、null を処理する最小限のパーサーが使用されます。フォールバックモードでは、アンカー、エイリアス、タグ、フロースタイル、マージキー、複数ドキュメントのストリームなど、複雑な YAML 機能はサポートされません。
• YAML の複数ドキュメント： コンバーターは YAML 入力を単一のドキュメントとして扱います。変換の前に、複数ドキュメントの YAML を別々のファイルに分割してください。
• TOML の型に関する制限： TOML 出力でサポートされるのは、基本的なスカラー値、スカラー値の配列、ネストされたテーブルです。混在する配列、テーブルの配列、タグ付きの値、任意のオブジェクトは、明確なメッセージとともに拒否されます。

依存関係

ほとんどの変換では Python 標準ライブラリのみを使用します。2 つの変換には外部ツールが必要です。

Markdown→PDF 用の Pandoc

Markdown→PDF では pandoc を呼び出します。pandoc が見つからない場合、CLI は次のように出力します。

Markdown to PDF requires pandoc. Install pandoc and ensure it is on PATH.

オペレーティングシステムのパッケージマネージャー、または https://pandoc.org/installing.html から pandoc をインストールしてください。PDF はバイナリ形式のため、PDF の出力先パスが必要です。標準出力には書き込めません。

Excel→CSV 用の openpyxl

Excel の読み込みには openpyxl が必要です。

python -m pip install openpyxl

インストールされていない場合、CLI はインストール方法のヒントを出力して、ゼロ以外の終了コードで終了します。コンバーターが読み込むのは最初のワークシートのみです。名前付きシート、Excel による数式の評価、書式、複数の CSV ファイルが必要な場合は、スプレッドシートツールまたは簡単なカスタムスクリプトを使用してください。

よくある落とし穴

1. CSV の往復変換で損失がないと期待する。 CSV にはスキーマ、ネスト、信頼できる型情報がありません。JSON→CSV のフラット化は確認やインポートには実用的ですが、可逆性のあるアーカイブ形式ではありません。
2. HTML のレイアウトが保持されると思い込む。 HTML→Markdown／テキストで保持されるのはコンテンツの構造であり、CSS、スクリプト、セル結合のあるテーブル、ブラウザーでの正確な空白ではありません。
3. 高度な YAML にフォールバック YAML を使う。 アンカー、エイリアス、タグ、フロースタイルのマップ／リスト、マージキー、複数ドキュメントのストリームには実際の YAML パーサーが必要です。また、書き戻す際にアンカーの同一性が失われる場合があります。
4. すべての JSON を TOML に書き込む。 TOML では JSON のあらゆる形式を表現できません。配列はスカラー値で構成され、TOML の利用側が処理できる程度に一貫している必要があります。オブジェクトはテーブルになります。
5. 依存関係を忘れる。 PDF には pandoc、Excel には openpyxl が必要です。自動化に頼る前に、両方をインストールしてください。
6. Markdown の文章とテーブルを混在させる。 Markdown→CSV では、見つかった最初のパイプテーブルが読み込まれ、周囲の文章は無視されます。

このスキルが行わないこと

• OCR は行いません。 スキャンされた PDF や画像をテキストに変換するには、事前に OCR パイプラインが必要です。
• PDF の抽出は行いません。 ここでは Markdown→PDF による PDF の書き出しのみをサポートします。PDF からテキストやテーブルを抽出するには、専用の PDF／OCR スキルを使用してください。
• バイナリ形式の Office ファイル編集は行いません。 .docx、書式付き .xlsx の生成、差し込み印刷のワークフローは、このコンバーターの対象外です。Word／Excel テンプレートへの入力には fill-template を使用してください。
• 書式に大きく依存するレイアウトの保持は行いません。 このツールは、ピクセル単位で忠実な出版ではなく、移植性の高いテキスト／データ変換を目的としています。

検証チェックリスト

• ソース形式とターゲット形式がマトリクスに含まれていることを確認します。
• ファイルに出力する場合は --output を使用し、標準出力のテキストで問題ない場合に限り省略します。
• 多数のファイルを一括変換する前に、出力サンプルを確認します。
• JSON→CSV では、フラット化された列名とリストのシリアル化を確認します。
• YAML/TOML では、高度な機能が不要であること、または黙って失われていないことを確認します。
• PDF/Excel では、自動化に依存する前に pandoc と openpyxl がインストールされていることを確認します。