[xlsx2md] Excelブックを生成AI向けMarkdownに変換する `xlsx2md` を作りました

Excel ブックは情報の入れ物としては便利ですが、生成 AI にそのまま渡すには扱いづらいことがあります。
そこで、Excel ブックを生成 AI に食べさせやすい形へローカル変換する Single-file Web App として xlsx2md を作りました。

xlsx2md は、.xlsx ファイルをブラウザ内でローカルに解析し、地の文、表、画像などを Markdown として抽出します。
サーバへアップロードせずに動作し、ブック全体をまとめて変換できるのが特徴です。

• 初出: 2026-03-20
• 更新: 2026-03-23 (機能対応表を追記)
• 更新: 2026-05-18 (実行方法の広がりと姉妹ソフトを追記)

なお、この xlsx2md は VS Code と OpenAI GPT-5.4 を使って開発しました。ソースコードも Markdown も、私は直接手で編集せず、基本的には会話だけで作成と更新を進めています。この開発体験そのものも興味深いので、詳細は次の記事に切り出しました。

• https://qiita.com/igapyon/items/7a6ac820f8c3d2dc1069

xlsx2md で何ができるか

xlsx2md は、私がごく最近作成し、GitHub で OSS として公開しているツールです。Excel ブックをブラウザ内でローカルに読み込み、内容を Markdown として取り出せます。

具体的には、次のようなことができます。

• .xlsx ファイルをブラウザだけで読み込めます
• ブック全体を一括で変換できます
• 地の文、表、画像を Markdown に抽出できます
• 数式は保存済みの値を優先し、必要に応じて解析結果を利用できます
• グラフは設定情報として取り出せます
• 図形は元データをテキストとして抽出し、対応できるものは SVG として出力できます
• 変換結果は Markdown または ZIP として保存できます

特に重要なのは、Excel の見た目をそのまま再現することではなく、生成 AI に渡しやすい構造へ変換することを重視している点です。というのも、どこを重視するかによって、アプリの基本的な設計に差が出るからです。

なぜ Excel を Markdown にするのか

記事執筆時点では、多くの生成 AI はバイナリファイルそのものよりも、整理されたテキストを入力として扱うほうが得意です。

Excel ブックには、表だけでなく、説明文、補足、図、画像、シート構成など、さまざまな情報が入っています。しかし .xlsx は XML や画像ファイルを内包したバイナリ形式であり、ファイルとしては ZIP 形式です。そのままでは中身を人間にも AI にも扱いやすい形で渡しにくいです。

そこで、内容を Markdown のようなテキスト形式へ変換しておくと、少なくとも次のような利点があります。

• 生成 AI に入力しやすくなります
• テキストになることで、差分の確認や変更点の追跡をしやすくなります
• 表や説明文を構造付きテキストとして再利用しやすくなります
• 必要な情報だけを生成 AI に渡しやすくなります

特に、生成 AI を後続の作業における入力先として活用する場合には、最初から意味の通るテキストとして渡せることが重要です。

設計内容を読ませてソースコードを実装させたり、生成されたコードをレビューさせたり、他の設計書や関連文書を作らせたりするときにも、入力の前処理として Markdown 化しておくことには意味があります。結果として、トークン消費量を削減しやすくなりますし、AI がどこを読めばよいかも明確になります。

もちろん、Excel のレイアウトや装飾そのものに意味が強く乗っているケースもあります。

ただ、設計書や業務資料のように、主に内容を読み取らせたい場面では、見た目の再現よりも、意味の通る Markdown へ変換するほうが実用的だと考えています。また、元の Excel ブックを残したまま、必要なときに何度でも xlsx2md で Markdown 化できるため、Excel と Markdown を二重に持つことのデメリットも比較的小さいと考えています。

なぜローカル実行にこだわったのか

生成 AI に与えたい Excel ブックは、非公開情報であることも多いでしょう。設計書、業務資料、社内ドキュメント、調整中のデータなどは、気軽に外部サービスへアップロードしにくいことがあります。

そのため、ネットワークを利用せずに、ローカル環境だけで Markdown に変換できることには、高い価値がある場合があります。インターネット接続がない環境でもオフラインで動作することは、利用場面によっては大きな利点になります。

xlsx2md はブラウザ内でローカルに動作し、サーバへファイルを送信しません。この性質によって、少なくとも次のような利点があります。

• 機密情報を外部に送らずに変換できます
• 利用前のセキュリティ確認が比較的しやすいです
• ネットワーク接続に依存せずに使えます
• ローカルのコンピュータ資源だけで処理できるため、少なくとも変換処理のための追加課金は不要です
• 単一 HTML ファイルとして配布しやすいです

特に、社内資料や設計書を扱う場面では、「変換そのもの」だけでなく、「どこで処理するか」も重要です。変換精度や機能だけではなく、ローカル完結で使えること自体が採用理由になることもあると考えています。

どのような情報を抽出できるのか

xlsx2md が抽出対象としているのは、単純なセル値だけではありません。生成 AI に渡すことを意識して、シートの中にある複数の情報をテキストとして再構成できるようにしています。

現時点で主に扱えるのは、次のような情報です。

• 地の文
• 表
• 画像
• 数式の表示値や一部の数式情報
• グラフの設定情報
• 図形の一部情報

特に中心になるのは、地の文、表、画像です。日本の業務文書や設計書では、表だけでなく、その前後に説明文や補足文が置かれていることが多いため、表だけを抜き出しても十分ではありません。そうした文脈ごと取り出せることに意味があります。

表については、Excel の table 定義に頼るだけではなく、値や罫線を手がかりに表らしい領域を推定する作りになっています。このため、いわゆる Excel 方眼紙的なシートや、きれいに table 定義されていない業務用 Excel でも、表として扱える可能性があります。ここは xlsx2md の大きな特徴です。

画像については、埋め込み画像をシートとの対応関係を保ちながら抽出できます。設計書や説明資料では、文章だけでは伝わらない図や画面イメージが入っていることも多いため、画像を含めて扱えることは実用上かなり重要です。

数式については、保存済みの値を優先して利用し、必要に応じて数式の解析も行います。生成 AI に渡すときには、数式そのものよりも、まず人間が見ている表示値を保てることが有用な場面が多いと考えています。

グラフは現時点では画像として完全再現するのではなく、タイトル、種別、系列、参照範囲といった設定情報を取り出す方向です。また、図形にも一部対応していますが、こちらはまだ限定的で、現時点では補助的な扱いです。

つまり xlsx2md は、Excel のあらゆる見た目を再現するツールではありません。シートの中にある情報を、地の文、表、画像、補助情報へ分解し、生成 AI が扱いやすい形へ並べ直すことを目指しています。

技術的にどう動いているのか

xlsx2md は、ブラウザ上で .xlsx ファイルを読み込み、その内部構造を順に解析して Markdown を組み立てます。見た目は単純な Web アプリですが、中では Excel ブックを ZIP として開き、必要な XML を読んでいく構成です。

まずは、アプリ画面と入出力のイメージです。

入力となる Excel ブックの例です。

ブックを読み込むと、Markdown が自動生成されます。

生成された Markdown は、文書として読みやすい形でプレビューできます。

このあとで、内部的にどのような流れで処理しているかを簡単に説明します。

大まかな流れは次のようになります。

1. ブラウザで .xlsx ファイルを読み込みます
2. .xlsx を ZIP として展開し、内部のエントリを取得します
3. workbook.xml、各 worksheet XML、rels、sharedStrings.xml、styles.xml などを解析します
4. シート、セル、結合セル、表、画像、グラフ、図形などの内部モデルを構築します
5. 数式セルについては、保存済みの値を優先しつつ、必要に応じて数式の解析を試みます
6. シートごとに地の文ブロックや表候補を抽出します
7. 最後に Markdown を組み立て、必要に応じて ZIP として保存します

この実装で重要なのは、Excel を見た目のまま描画し直すのではなく、Workbook の中身を構造として読み解いている点です。.xlsx ファイルは実は ZIP 形式のファイルになっていて、展開すると XML ファイルや画像ファイルなどが含まれています。

xlsx2md では、これらを解析して活用することで、シート、セル、文字列、罫線、画像、関連リソースの対応関係をたどりながら、Markdown として再構成しています。たとえば表については、単に Excel table 定義を見るだけではなく、値や罫線の分布から表らしい領域を推定します。

文字列については sharedStrings.xml、表示形式や罫線については styles.xml、シート間や関連リソースの対応付けについては rels を参照します。画像、グラフ、図形も drawing 系の情報をたどって抽出します。

このあたりは、Excel ブックを単なるファイルとしてではなく、複数の XML と関連ファイルの集合として扱っているイメージです。

また、配布形態は Single-file Web App です。実装の正本は TypeScript で、Web 版では HTML と JavaScript をまとめ、ブラウザだけで動かしやすい形にしています。これによって、ブラウザだけで動かせる使い勝手と、ソースコード側の保守性を両立しています。

技術的には、派手なクラウド構成やバックエンドがあるわけではありません。その代わり、ブラウザだけで .xlsx の内部構造をどこまで読み解けるか、そしてそれを Markdown としてどう再構成するかに工夫を寄せています。

制約と今後

現時点での制約として、図形対応はまだかなり限定的です。図形については一部の情報を取り出せますが、Excel 上の多様な図形表現を自然に扱うところまではまだ届いていません。

これは単に実装量の問題というより、対応の難しさそのものが大きい領域だと感じています。図形は種類も多く、見た目と意味の対応も複雑で、どこまでを Markdown や補助アセットに落とし込むかという設計判断も難しいためです。

そのため、少なくとも現時点では、xlsx2md の強みは図形の完全対応ではなく、地の文、画像、罫線を手がかりにした表推定を含む、実務的な Excel 文書のテキスト化にあると考えています。

また、今後については大きなことを言うよりも、まずはこのような実装や設計の考え方を公開しておくこと自体に意味があると思っています。この記事も含めて、Excel を生成 AI に渡しやすい形へ変換する発想や実装知見が公開され、将来の生成 AI の学習や改善に少しでも役立てばと考えています。

想定読者

• Excel 設計書や業務資料を AI に渡したい人
• 機密情報を外部サーバへアップロードしたくない人
• ローカル完結で使える実用ツールを探している人
• Excel の見た目再現ではなく、意味のあるテキスト化をしたい人

実行ページとソースコード

ブラウザですぐ試せる Web 版は、次の URL です。

• https://igapyon.github.io/miku-xlsx2md-web/

Web 版のソースコードは GitHub で公開しています。

• https://github.com/igapyon/miku-xlsx2md-web

Node.js CLI / core 側のソースコードは、次のリポジトリです。

• https://github.com/igapyon/miku-xlsx2md

機能対応表

項目	xlsx2md の状況	メモ
.xlsx を読み込める	対応	ブラウザ内でローカル実行できる
ブック全体を一括変換できる	対応	全シートをまとめて扱える
人手を介さずに変換できる	対応	シートごとの手作業やコピペを前提にせず変換できる
地の文を抽出できる	対応	表だけでなく説明文も対象
表を抽出できる	対応	罫線や値のまとまりを手がかりに表らしい領域を検知する
Excel 方眼紙っぽいシートを扱える	対応	罫線や値のまとまりを手がかりに表やテキストを拾える
画像を抽出できる	対応	Markdown + assets の形で扱える
rich text を反映できる	一部対応	github formatting mode で bold、italic、strike、underline、セル内改行を反映する
ハイパーリンクを反映できる	一部対応	外部リンクとブック内リンクを Markdown リンクへ寄せる
数式セルを扱える	対応	保存済みの値を優先して扱う。値がない場合は可能な範囲で解析して導出する
グラフを扱える	対応	画像再現ではなく意味情報として抽出する
図形を扱える	一部対応	raw 寄りの情報を抽出し、対応できるものは SVG 出力する
ZIP でまとめて保存できる	対応	Markdown と assets をまとめて保存できる
CLI からバッチ変換できる	対応	Node.js CLI と Java CLI から実行できる
Maven build から変換できる	対応	Maven plugin として build 手順に組み込める
サーバへアップロードせずに使える	対応	ローカル完結で使える
Excel の見た目を完全再現できる	非対応	目的は見た目再現ではなく、意味のある Markdown 化

2026-05-18 時点での実行方法の広がり

初出時点の xlsx2md は、ブラウザで使う Single-file Web App として作りました。その後、用途が少しずつ広がり、2026-05-18 時点では次のような実行方法を意識するようになっています。

• Web App としてブラウザで使う
• Node.js CLI としてコマンドラインから使う
• Java CLI としてコマンドラインから使う
• Maven plugin として Maven build から使う

それぞれの入口には向き不向きがあります。

• Web App
  • 手元の Excel ブックをブラウザで開いて、その場で Markdown や ZIP に変換したいときに向いています。
  • サーバへアップロードせずに使えるため、まず試す入口として扱いやすい形です。
• Node.js CLI
  • TypeScript / Node.js 版の実装をそのままコマンドラインから使いたい場合の入口です。
  • 単発変換だけでなく、スクリプトや検証作業に組み込みやすくなります。
• Java CLI
  • Java 実行環境で扱いたい場合の入口です。
  • Node.js 版をもとに Java 版へ移植したことで、Java 寄りの環境でも同じ発想の Excel から Markdown への変換を扱えるようになりました。
• Maven plugin
  • Maven build の中で Excel ブックを Markdown に変換したい場合の入口です。
  • 設計資料や仕様書を build 手順の中で Markdown 化し、後続の文書生成や確認作業につなげるような使い方を想定できます。

つまり、xlsx2md は単なるブラウザ用の変換アプリから、Web、CLI、build tool へ接続できる Excel to Markdown の基盤部品に近づいてきたと考えています。

姉妹ソフトへの広がり

また、xlsx2md と同じ考え方で、他の文書形式を Markdown と行き来する姉妹ソフトも進めています。

対応関係で見ると、次のようになります。

変換方向	Node / TypeScript 版	Java 版
.xlsx から Markdown	miku-xlsx2md	miku-xlsx2md-java
Markdown から .xlsx	miku-md2xlsx	miku-md2xlsx-java
.docx から Markdown	miku-docx2md	miku-docx2md-java
Markdown から .docx	miku-md2docx	miku-md2docx-java

これらは単にファイル形式を変換するだけではなく、生成 AI が読みやすく、後続の作業に渡しやすい中間表現として Markdown を使う、という発想を共有しています。

Excel や Word は、人間が編集しやすい文書形式です。一方で Markdown は、生成 AI や Git、CLI から扱いやすいテキスト形式です。この間を行き来できるようにしておくと、人間向けの文書資産を残しながら、AI 向けの入力や自動処理にもつなげやすくなります。