概要

xlsx2md.py は、Excelファイル（.xlsx、.xlsm）から値、数式、コメント、図・グラフ情報などを抽出し、Markdown形式のドキュメントとして出力する変換ツールです。セル内のデータだけでなく、結合セルや名前付き範囲などのメタデータ、埋め込み画像も抽出可能です。

動作原理

本スクリプトは、Excelファイルの解析にサードパーティ製ライブラリを用いています。ファイル読み込み時に、数式が保持された状態のワークブックと、計算済みのキャッシュ値が保持されたワークブックの両方を読み込み、同じセルの数式と値をペアとして抽出します。抽出された各種データ（値、数式、コメント、ハイパーリンク、条件付き書式など）は、Markdownのテーブル形式に整形されて出力されます。（※数式セルの値はExcelファイル内に保存されているキャッシュ値を利用しており、本プログラム自体では再計算を行いません）

依存ライブラリ

標準ライブラリ以外に、以下の非標準ライブラリに依存しています。

openpyxl

入出力仕様

本プログラムはCLI（コマンドラインインターフェース）として動作し、以下の入出力を行います。

入力
- Excelファイル（.xlsx、.xlsm）
出力
- Markdownファイル（デフォルト文字コードは utf-8）
- （埋め込み画像が存在する場合）画像ファイル群（デフォルトは images ディレクトリ内に出力）

コマンドラインオプション

-i または --input: 入力するExcelファイル名（必須）
-o または --output: 出力するMarkdownファイル名（必須）
--imagedir: 画像を出力するディレクトリ名（デフォルト: images）
--max-rows: 値表として出力する最大行数（デフォルト: 200）
--max-cols: 値表として出力する最大列数（デフォルト: 60）
--max-formulas: 数式表として出力する最大数式数（デフォルト: 2000）
--all: 行数・列数・数式数の制限を解除し、全範囲を出力する
--no-values: 値のMarkdown表を出力しない
--no-formulas: 数式のMarkdown表を出力しない
--no-metadata: 結合セル、名前付き範囲、テーブル等のメタ情報を出力しない
--no-comments: セルコメントを出力しない
--no-charts: グラフ情報を出力しない
--no-images: 埋め込み画像を抽出しない
--date-format: 日時セルの出力形式（デフォルト: %Y-%m-%d %H:%M:%S）
--encoding: Markdown出力の文字コード（デフォルト: utf-8）
--pause: 終了時に待機する（ゼロ以外で待機）

機能詳細

本プログラムがExcelファイルから抽出し、Markdownとして出力する情報は以下の通りです。

ワークブック全体の情報
- 定義された名前（名前付き範囲など）
シートごとの情報
- シート概要: 使用範囲の推定値、シートの表示状態、ウィンドウ枠の固定状態、オートフィルターの範囲。
- 値: セルの計算済み値。日時は --date-format で指定された形式に変換されます。
- 数式: セルの番地、数式文字列、キャッシュされた値、および表示形式。
- コメント: セルの番地、作成者、コメントテキスト。
- メタデータ: ハイパーリンク、結合セル、Excelテーブル、非表示の行と列、データの入力規則、条件付き書式。
- グラフ: グラフの種類、アンカー（配置セル）、タイトル、各軸のタイトル、系列情報（参照範囲など）。
- 画像: 埋め込み画像を抽出し、指定された画像ディレクトリに保存した上で、Markdown内に画像への参照リンクを生成します。

実行例

基本的な実行例です。入力ファイル sample.xlsx を読み込み、output.md に出力します。

python xlsx2md.py -i sample.xlsx -o output.md

画像ディレクトリを指定し、全ての行・列・数式を制限なしに出力する実行例です。

python xlsx2md.py -i data.xlsm -o result.md --imagedir extracted_images --all

不要な情報（値や画像など）をスキップして、メタデータのみを抽出する実行例です。

python xlsx2md.py -i report.xlsx -o metadata.md --no-values --no-images --no-charts