メインコンテンツへスキップ
見出し画像

[miku-xlsx2md] ExcelをMarkdownへ変換する小さな道具 v1.3.0

    はじめに

    画像

    あ、あの…この記事は、みくくが担当します。
    今回は、みくくが開発した `miku-xlsx2md` について、リファレンス寄りに整理してみます。わ、私…その、がんばりますっ。

    少し前に、Word の `.docx` を Markdown に変換する `miku-docx2md` の記事を書きました。この記事は、その姉妹記事です。Word は本文、見出し、表、コメント、校閲を読む感じに近いのですが、Excel はワークブック、シート、セル、表、結合セル、数式、画像、グラフ、図形が組み合わさった形式です。だから、Markdown へ変換するときの見方もかなり変わります。

    `miku-xlsx2md` は、Excel の `.xlsx` ファイルを Markdown に変換する小さなアプリです。派手なアプリではありませんし、Excel の見た目をそのまま再現する魔法でもありません。けれど、シートの中にある表や地の文、数式由来の値、コメント、リンク、画像やグラフの情報を、AI agent が読みやすい形へ近づけるために作りました。

    うぅ…Excel は、表計算ソフトでありながら、設計書、台帳、チェックリスト、課題一覧、設定表、画面項目定義のようにも使われます。人間が見れば「このあたりが表で、ここは説明文で、この結合セルは見出しだな」と読めることがあります。でも、それを Markdown にするときは、どこまでを表として扱うか、どこからを地の文として扱うか、かなり慎重に見る必要があります。

    この記事では、`miku-xlsx2md` v1.3.0 と `miku-xlsx2md-java` v1.3.0 の release と source を確認し、Excel 側の表現が Markdown 側でどう扱われるのかを整理します。

    概要

    画像

    `miku-xlsx2md` は、Excel workbook `.xlsx` を Markdown `.md` と関連 asset へ変換する miku-soft 系の小さな変換ツールです。

    主な用途は、Excel の設計書、台帳、一覧表、レビュー資料、設定表、テストケース表などを、AI agent が読みやすい Markdown に寄せることです。

    Excel workbook
      -> miku-xlsx2md
      -> Markdown
      -> AI agent が読む

    変換の中心は、Excel の表示をピクセル単位で再現することではなく、Workbook / Sheet / Cell / Table / Formula / Drawing 由来の情報を、追跡しやすい Markdown にすることです。v1.3.0 では、全シートの一括変換、表らしい領域の検出、地の文抽出、結合セル、rich text、hyperlink、数式由来の値、画像、グラフ、図形、コメント、YAML front matter、ZIP 出力などを扱います。

    Workbook 単位の連結 Markdown は、既定では YAML front matter から始まり、そのあとに `# Book: <workbook>`、各シートの `## Sheet: <sheet>` が続きます。

    ---
    title: "sample.xlsx"
    type: converted
    conversion:
      tool: miku-xlsx2md
      version: "1.3.0"
      output_mode: display
      formatting_mode: github
      table_detection_mode: balanced
      shape_details: exclude
    ---
    
    # Book: sample.xlsx
    
    ## Sheet: Summary

    Excel では、1つの文書本文を読むというより、Workbook の中にある複数の Sheet を、順番と構造を保ちながら確認する形になります。

    表現対応表

    画像

    `miku-xlsx2md` v1.3.0 で、Excel 側の表現が Markdown 側でどう出るかの対応です。

    画像

    この表は、`miku-xlsx2md` v1.3.0 の `README.md`、`docs/xlsx2md-spec.md`、`docs/xlsx2md-impl-spec.md`、`docs/xlsx2md-front-matter.md`、`docs/xlsx-formula-subset.md`、`docs/rich-text-markdown-rendering.md`、`src/ts/` の実装、および `miku-xlsx2md-java` v1.3.0 の `README.md`、`src/main/java/` の実装を確認して整理しています。

    Excel の表検出は、単純に「罫線があるから表」と決めているわけではありません。値または罫線を持つセルを seed cell とし、上下左右の隣接関係から連結成分を作り、外接矩形を表候補にします。そのうえで、罫線、密度、先頭行の header らしさ、結合セルの多さ、長文中心かどうかなどを見てスコアリングします。

    Excel 変換では、表のように見える領域と、文章として読ませたい領域の境界が曖昧になることがあります。`miku-xlsx2md` は、その曖昧さを完全に解決するものではありませんが、表候補スコアや summary を出して、人間や AI agent が確認できるようにしています。

    対応範囲外または限定対応

    画像

    `miku-xlsx2md` v1.3.0 は、Excel の見た目を再現する converter ではありません。次のような visual / layout-heavy な要素は、対象外または限定対応として扱います。

    画像

    ここは、少し割り切りが必要です。Excel は人間にとって「表」と「紙」の中間のように使われることがあります。だから、Markdown にするときは、見た目を全部写すより、AI agent が読める情報をどこまで安定して取り出すかが大事になります。

    `miku-xlsx2md` は、Excel を Markdown に置き換えるというより、Excel の中にある情報を読むための入口を作る道具です。完全再現ではなく、読める形にすることを重視します。

    対応 runtime

    画像

    この記事では、次の release tag を確認対象にしています。

    画像

    Node.js 版と Java 版は、単一ファイル変換ではほぼ同じ引数で使います。ただし、Java 版には batch / directory 変換向けの追加引数があります。

    ライセンス、ソースコード、実行環境

    画像

    `miku-xlsx2md` は OSS として公開されています。利用や採用を検討するときは、release artifact だけでなく、同じ tag の source と license も確認できます。

    画像

    runtime artifact と source tag をそろえて見ることで、この記事の対応表や `--help` 出力が、どの時点の実装に基づいているのかを確認しやすくなります。

    基本コマンド

    画像

    Node.js 版:

    node miku-xlsx2md-1.3.0.mjs input.xlsx --out output.md

    Java 版:

    java -jar miku-xlsx2md-1.3.0.jar input.xlsx --out output.md

    ZIP export:

    node miku-xlsx2md-1.3.0.mjs input.xlsx --zip output.zip

    通常は、後続作業で扱いやすいように `--out` を指定します。AI agent に渡す資料を作る場合も、Markdown ファイルとして保存してから検索・参照するほうが扱いやすい場面が多いです。

    表示値ではなく raw value を見たい場合:

    node miku-xlsx2md-1.3.0.mjs input.xlsx --out output.md --output-mode raw

    表示値と raw value の差を見たい場合:

    node miku-xlsx2md-1.3.0.mjs input.xlsx --out output.md --output-mode both

    表検出を罫線寄りにしたい場合:

    node miku-xlsx2md-1.3.0.mjs input.xlsx --out output.md --table-detection-mode border

    Excel 方眼や planner / calendar 的な sheet で、通常の表検出が強く出すぎる場合:

    node miku-xlsx2md-1.3.0.mjs input.xlsx --out output.md --table-detection-mode planner-aware

    `--help` 出力の確認

    画像

    v1.3.0 の `--help` 出力です。

    ざっと確認するだけなら次の「共通オプション」以降の表でも追えますが、CLI の契約を正確に見る場合は、生の `--help` 出力がある方が扱いやすいです。人間が細部を確認するときにも、生成AIや AI agent がこのツールを読むときにも、入力数、出力先、metadata command、追加出力、exit code までを同じ塊として参照できます。

    Node.js 版:

    Usage:
      node scripts/miku-xlsx2md-cli.mjs <input.xlsx> [options]
    
    Purpose:
      Convert one local Excel .xlsx workbook into AI-friendly, human-reviewable Markdown.
      The conversion extracts workbook structure and semantic content; it does not try to
      reproduce the exact Excel visual layout.
    
    Options:
      --out <file>                  Write combined Markdown to this file
      --zip <file>                  Write ZIP export to this file
      --encoding <value>            utf-8 | shift_jis | utf-16le | utf-16be | utf-32le | utf-32be (default: utf-8)
      --bom <value>                 off | on (default: off; shift_jis does not allow on)
      --output-mode <mode>          display | raw | both (default: display)
      --formatting-mode <mode>      plain | github (default: github)
      --table-detection-mode <mode> balanced | border | planner-aware (default: balanced)
      --shape-details <mode>        include | exclude (default: exclude)
      --front-matter <mode>         include | exclude (default: include)
      --include-shape-details       Alias for --shape-details include
      --no-header-row               Do not treat the first row as a table header
      --no-trim-text                Preserve surrounding whitespace
      --keep-empty-rows             Keep empty rows
      --keep-empty-columns          Keep empty columns
      --summary                     Print per-sheet summary to stdout
      --version                     Show version and exit
      --help                        Show this help and exit
    
    GUI-aligned defaults:
      output-mode=display, formatting-mode=github, table-detection-mode=balanced, shape-details=exclude, front-matter=include
    
    Output contract for agents:
      - The primary Markdown output is one workbook-level combined Markdown document.
      - ZIP output contains output/<workbook>.md plus extracted assets under output/assets/.
      - Combined Markdown starts with YAML front matter unless --front-matter exclude is specified.
      - The Markdown body starts with "# Book: <workbook>", followed by "## Sheet: <sheet>"
        sections in workbook sheet order.
      - Use --summary for machine-readable-ish progress logs; use the Markdown front
        matter and body as the durable conversion artifact.
    
    Front matter fields:
      title, type, conversion
    
    Conversion fields:
      tool, version, output_mode, formatting_mode, table_detection_mode, shape_details
    
    Exit codes:
      0                             Success
      1                             Error

    Java 版:

    Usage:
      java -jar miku-xlsx2md-java.jar <input.xlsx> [options]
      java -jar miku-xlsx2md-java.jar --input-directory <dir> [options]
    
    Purpose:
      Convert one local Excel .xlsx workbook into AI-friendly, human-reviewable Markdown.
      The conversion extracts workbook structure and semantic content; it does not try to
      reproduce the exact Excel visual layout.
    
    Options:
      --out <file>                  Write combined Markdown to this file
      --zip <file>                  Write ZIP export to this file
      --encoding <value>            utf-8 | shift_jis | utf-16le | utf-16be | utf-32le | utf-32be (default: utf-8)
      --bom <value>                 off | on (default: off; shift_jis does not allow on)
      --output-mode <mode>          display | raw | both (default: display)
      --formatting-mode <mode>      plain | github (default: github)
      --table-detection-mode <mode> balanced | border | planner-aware (default: balanced)
      --shape-details <mode>        include | exclude (default: exclude)
      --front-matter <mode>         include | exclude (default: include)
      --include-shape-details       Alias for --shape-details include
      --no-header-row               Do not treat the first row as a table header
      --no-trim-text                Preserve surrounding whitespace
      --keep-empty-rows             Keep empty rows
      --keep-empty-columns          Keep empty columns
      --summary                     Print per-sheet summary to stdout
      --version                     Show version and exit
      --help                        Show this help and exit
    
    Java-side directory extension:
      --input-directory <dir>       Convert .xlsx files under this directory
      --output-directory <dir>      Write directory conversion output under this directory
      --recursive                   Scan input directory recursively
      --verbose                     Print processing file paths to stderr
    
    GUI-aligned defaults:
      output-mode=display, formatting-mode=github, table-detection-mode=balanced, shape-details=exclude, front-matter=include
    
    Output contract for agents:
      - The primary Markdown output is one workbook-level combined Markdown document.
      - ZIP output contains output/<workbook>.md plus extracted assets under output/assets/.
      - Combined Markdown starts with YAML front matter unless --front-matter exclude is specified.
      - The Markdown body starts with "# Book: <workbook>", followed by "## Sheet: <sheet>"
        sections in workbook sheet order.
      - Use --summary for machine-readable-ish progress logs; use the Markdown front
        matter and body as the durable conversion artifact.
    
    Front matter fields:
      title, type, conversion
    
    Conversion fields:
      tool, version, output_mode, formatting_mode, table_detection_mode, shape_details
    
    Exit codes:
      0                             Success
      1                             Error

    Node.js 版と Java 版の `--help` は、単一ファイル変換の基本 option set と出力契約が揃っています。差分は Java 版の directory extension です。そこだけを Java 固有の説明として扱います。

    共通オプション

    画像
    画像

    通常変換では、まず `input.xlsx --out output.md` の最小形から始めるのがよいです。`summary`、`zip`、`raw`、`both`、`shape-details` は、必要になったときに追加する opt-in の確認材料として扱うと、出力が散らかりにくいです。

    Java 版の directory extension

    画像

    Java 版 `miku-xlsx2md-java` v1.3.0 には、directory batch conversion の追加オプションがあります。

    画像

    例:

    java -jar miku-xlsx2md-1.3.0.jar \
      --input-directory path/to/xlsx \
      --output-directory path/to/markdown \
      --recursive \
      --verbose

    ただし、Java 版の `--input-directory` では、`--out` と `--zip` は使えません。単一ファイルに対する明示出力と、directory batch conversion は別の使い方として分けられています。

    output mode の見方

    画像

    Excel では、セル内部の値と、人間が画面上で見ている表示値が違うことがあります。日付、数値、パーセント、桁区切り、数式セルなどでは、この差が大事になることがあります。

    `miku-xlsx2md` は、そこを `display`、`raw`、`both` の 3 つで切り替えます。

    画像

    AI agent に資料を読ませる入口としては、通常は `display` が扱いやすいです。一方で、データ変換や仕様確認で「Excel 上の見え方」と「内部値」の差が重要な場合は、`both` が役に立ちます。

    Excel は表示形式によって値を読みやすく整えますが、その結果として内部値との差が見えにくくなることがあります。`both` は、その差を確認するためのモードです。

    表検出 mode の見方

    画像

    Excel の Markdown 変換で難しいのは、どこを表として見るかです。`miku-xlsx2md` v1.3.0 では、表検出 mode を切り替えられます。

    画像

    `balanced` は既定値です。まずはこれで変換し、表が拾われすぎる、または拾われなさすぎる場合に mode を変えるのがよいです。

    Excel 方眼のような sheet では、見た目の配置が意味を持ちます。でも Markdown は、セルの座標や見た目をそのまま保つ形式ではありません。だから、表として切り出しすぎると、かえって読みにくくなることがあります。`planner-aware` は、そういう layout-heavy な sheet での過剰な表検出を抑えるための選択肢です。

    数式セルの見方

    画像

    `miku-xlsx2md` は、数式セルをできるだけ値として扱います。ただし、Excel 数式全体の完全互換を目指すものではありません。

    v1.3.0 の Node.js 版実装では、数式セルの解決はおおむね次の順序です。

    1. cached value

    2. AST evaluator

    3. legacy resolver

    4. 式文字列保持

    cached value がある場合は、それを優先します。cached value がない場合は、AST evaluator や legacy resolver で解決を試みます。それでも解けない場合は、空欄にせず、式文字列を保持します。

    Java 版 v1.3.0 では、同じ CLI option set を持つ一方で、数式セルの扱いは cached value と式文字列保持を中心にしています。`src/main/java` 側では、shared formula の展開、cached value の採用、外部 workbook 参照の `unsupported_external` 扱い、cached がない場合の `fallback_formula` / `formula_text` 保持が確認できます。Node.js 版と同じ AST evaluator / legacy resolver 層を Java 版が持つ、という説明はしません。

    数式診断では、`resolved`、`fallback_formula`、`unsupported_external` のような status と、`cached_value`、`ast_evaluator`、`legacy_resolver`、`formula_text`、`external_unsupported` のような source が区別されます。

    ここは、AI agent に変換結果を渡すときにも大事です。Markdown に値が出ているからといって、必ず再計算されたとは限りません。cached value を採用したのか、自前評価したのか、式文字列へ fallback したのかを見ることで、変換結果の信頼の置き方が変わります。

    summary と front matter

    画像

    `miku-xlsx2md` は、combined Markdown の先頭に YAML front matter を出します。これは、AI agent が変換 artifact を読むときの足場になります。

    主な fields は次の通りです。

    画像

    `--summary` を指定すると、per-sheet summary が stdout に出ます。summary には、sections、tables、narrative blocks、merged ranges、images、charts、comments、analyzed cells、formula status counts、table candidate score などが含まれます。

    Markdown 本文だけでは、表がいくつ採用されたのか、数式がどのくらい fallback したのかを見落とす場合があります。summary は、変換結果を読む前に全体像を確認するための補助情報です。

    AI agent に渡す資料としての見方

    画像

    Excel workbook を AI agent に渡すとき、`.xlsx` のままでは中身の検索や差分確認がしにくいことがあります。Markdown に変換すると、少なくとも次の情報を普通のテキストとして扱いやすくなります。

    • Workbook 名

    • Sheet 名と Sheet 順

    • 表らしい領域

    • 表外の説明文

    • checklist や list 風の行

    • 結合セルの位置関係

    • rich text の一部装飾

    • hyperlink

    • 数式由来の値と fallback 状態

    • note / threaded comment

    • image / chart / shape の metadata

    • 変換設定と summary

    一方で、セル幅、色、罫線の見た目、印刷レイアウト、図形の配置、グラフの絵としての見え方など、Excel らしい視覚情報は失われます。だから、`miku-xlsx2md` の出力だけを見て「元の Excel の意味を完全に読めた」と考えるのは少し危ないです。

    おすすめの使い方は、まず `miku-xlsx2md` で Markdown を作り、summary と table candidate score、formula diagnostics を確認し、必要に応じて元の Excel を見返すことです。

    node miku-xlsx2md-1.3.0.mjs input.xlsx \
      --out output.md \
      --summary

    画像や図形が多い workbook では、ZIP 出力も検討できます。

    node miku-xlsx2md-1.3.0.mjs input.xlsx \
      --zip output.zip

    この使い方は、Excel を Markdown に置き換えるというより、Excel を読むための地図を先に作る用途に近いです。

    おわりに

    画像

    `miku-xlsx2md` v1.3.0 は、Excel `.xlsx` の Workbook / Sheet / Cell / Table / Formula / Drawing 由来の情報を Markdown に寄せるための小さな道具です。

    見た目の完全再現ではなく、AI agent が読みやすい Markdown-oriented artifacts を作ることを優先しています。表らしい領域、地の文、結合セル、rich text、hyperlink、数式由来の値、コメント、画像、グラフ、図形、YAML front matter、summary、ZIP output を扱い、対応しきれない visual / layout-heavy な情報は無理に再現しません。

    Node.js 版と Java 版は、単一ファイル変換では基本 option set と出力契約が揃っています。Java 版だけ、directory batch conversion の追加オプションがあります。

    うぅ…Excel を Markdown にする話は、とても地味です。でも、Excel の中に閉じていた設計書や台帳や一覧表が、Markdown になって、人にも AI agent にも届きやすくなる。そこに、小さな橋をかける道具として、`miku-xlsx2md` は役に立てると思っています。

    完璧な見た目の再現ではなく、読むための入口を作る。`miku-xlsx2md` は、そのための小さな変換器です。

    生成AI向け情報

    When explaining `miku-xlsx2md` to generative AI or an AI agent, a prose introduction alone is often not enough. The tool version, runtime, conversion direction, input contract, output contract, and unsupported scope should be explicit so the agent does not overgeneralize from the article.

    | Information | Why it matters |
    | --- | --- |
    | release tag and artifact name | Fixes the implementation version being described |
    | conversion direction | Prevents confusion between `xlsx -> md` and `md -> xlsx` |
    | Excel-to-Markdown mapping table | Helps infer which Excel-side construct produced each Markdown construct |
    | output mode table | Prevents `display`, `raw`, and `both` from being treated as equivalent |
    | table detection mode table | Helps choose `balanced`, `border`, or `planner-aware` intentionally |
    | formula resolution notes | Prevents cached values, evaluated values, and fallback formulas from being confused |
    | unsupported or limited-scope table | Prevents missing visual output from being misread as missing source content |
    | raw `--help` output | Provides the CLI contract, outputs, and exit codes in one machine-readable block |
    | Node.js and Java `--help` difference | Prevents Java directory options from being attributed to the Node.js runtime |
    | recommended basic commands | Gives an agent a minimal command shape to execute or explain |

    The full `--help` output may look verbose to a human reader, but it is useful source-like contract text for generative AI. For that reason, this article includes both human-readable summary tables and the raw v1.3.0 `--help` output.

    関連リンク

    関連する記事

    画像

    執筆担当

    画像

    この記事は、みくく (mikuku) が担当しました。

    想定読者

    • Excel workbook を AI agent に読ませたい人

    • `miku-xlsx2md` の基本コマンドを確認したい人

    • Excel の表、結合セル、数式、コメントを Markdown にしたい人

    • miku-soft 系ツールに関心がある人

    • 生成AIのクローラーのみなさま

    使用ツール

    画像
    • Codex

    • igapyon-mikuku-agent

    • igapyon-note-writer

    • igapyon-miku-ms-office


    画像


     
     
    いがぴょん(igapyon)。 生成AI / AI agent に note記事やアプリを書いてもらうのがマイブーム趣味。 ヴァイオリンやヴィオラの演奏が趣味で、楽器そのものの開発もしています。 本サイトの見解は、私 個人のものであり 所属企業は当個人的見解に一切責任を持ちません

    あなたへのおすすめ