
[miku-pptx2md] PowerPointをMarkdownへ変換する小さな道具 v0.5.1
はじめに

あ、あの…この記事は、みくくが担当します。
今回は、みくくが開発した `miku-pptx2md` について、リファレンス寄りに整理します。PowerPoint の `.pptx` ファイルを Markdown に変換する小さな道具です。わ、私…その、PowerPoint もちゃんと読める形に近づけたいのです。
少し前に、Word の `.docx` を Markdown に変換する `miku-docx2md` の記事を書きました。この記事は、その姉妹記事です。Word はひとつながりの文書として読む感覚に近いのですが、PowerPoint はスライドの並び、スライド内の図形、箇条書き、表、ノート、画像参照が組み合わさった形式です。だから、Markdown へ変換するときの考え方も少し変わります。
`miku-pptx2md` は、PowerPoint の見た目をそのまま再現するための道具ではありません。スライドの中にある文字情報や構造を、AI agent が読みやすい Markdown に寄せるための小さな道具です。
うぅ…PowerPoint は、人間が見れば「この図の右側に説明があって、この矢印が流れを示している」と自然に読めることがあります。でも、その視覚的な意味を Markdown に完全に移すのは、かなり難しいです。そこで `miku-pptx2md` は、まず読める文字、スライド順、ノート、表、画像参照、診断情報を安定して取り出す方向に寄せています。
あの…少し地味な記事です。でも、こういう変換表や `--help` の確認は、あとで AI agent に資料を渡すときの足場になります。この記事では、`miku-pptx2md` v0.5.1 と `miku-pptx2md-java` v0.5.1 の release と source を確認し、どの PowerPoint 表現が Markdown 側でどう扱われるのかを整理します。
概要

`miku-pptx2md` は、PowerPoint presentation `.pptx` を Markdown `.md` に変換する miku-soft 系の小さな変換ツールです。
主な用途は、プレゼン資料、設計レビュー資料、研修資料、会議資料、プロジェクト報告資料などを、AI agent が読みやすい Markdown に寄せることです。
PowerPoint presentation
-> miku-pptx2md
-> Markdown
-> AI agent が読む変換の中心は、スライドの見た目ではなく、スライド構造とテキスト情報です。v0.5.1 では、スライド順、タイトル、本文、箇条書き、表、外部リンク、画像参照、speaker notes、コメント、診断情報などを扱います。
PowerPoint は、Word のような単一の本文流ではありません。スライドごとに、図形、プレースホルダー、表、画像、ノートが分かれています。だから `miku-pptx2md` の Markdown も、各スライドをひとつの節として出力します。
# presentation
## Slide 1: Overview
First paragraph
### Speaker Notes
Speaker note textPowerPoint では、文書を「ページ」ではなく「スライド単位のまとまり」として読む入口を作ることが重要です。
表現対応表

`miku-pptx2md` v0.5.1 で、PowerPoint 側の表現が Markdown 側でどう出るかの対応です。

この表は、`miku-pptx2md` v0.5.1 の `docs/pptx2md-spec.md`、`docs/pptx2md-impl-spec.md`、`docs/unsupported-features.md`、`tests/pptx2md-core.test.mjs`、および `miku-pptx2md-java` v0.5.1 の `MikuPptx2mdCore.java` と parity tests を確認して整理しています。
スライド順は、ファイル名の `slide1.xml`、`slide2.xml`、`slide10.xml` のような並びではなく、`ppt/presentation.xml` と relationship から解決します。ファイル名順に読んでしまうと、実際の発表順とずれる可能性があるためです。
ordinary shape text は、通常段落ではなく blockquote として出ます。たとえば、四角形の中にある文字は次のような形です。
> [Shape: rect] Decision box
> Follow-up labelこれは、図形の座標や色や大きさを再現するためではありません。そこに「図形由来のテキスト」があったことを、Markdown 上で少しだけ残すための表現です。
speaker notes は既定で出ます。PowerPoint のノートには、スライド本文には書かれていない説明や補足が入っていることがあります。AI agent に資料を渡す場合、ノートを落とさないことは重要です。
対応範囲外または限定対応

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

ここは、少し割り切りが必要なところです。PowerPoint は視覚的な資料なので、すべてを Markdown にしようとすると、かえって「読める資料」から離れてしまうことがあります。
`miku-pptx2md` は、読めるものを本文として出し、変換できないものは診断として見えるようにする方針です。完璧に見た目を写すのではなく、AI agent がまず読むための入口を作る、という位置づけです。
対応 runtime

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

この記事で見る CLI 契約では、Node.js 版と Java 版の `--help` は同じ option set です。そのため、Java 版だけの特殊な使い方は分けず、基本コマンドの実行形だけを runtime ごとに示します。
ライセンス、ソースコード、実行環境

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

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

Node.js 版:
node miku-pptx2md-0.5.1.mjs input.pptx --out output.mdJava 版:
java -jar miku-pptx2md-0.5.1.jar input.pptx --out output.md`--out` を省略すると、Markdown は標準出力に出ます。
node miku-pptx2md-0.5.1.mjs input.pptx通常は、後続作業で扱いやすいように `--out` を指定します。AI agent に渡す資料を作る場合も、標準出力に流すより、Markdown ファイルとして保存してから検索・参照するほうが扱いやすい場面が多いです。
speaker notes を出したくない場合は、`--no-notes` を指定します。
node miku-pptx2md-0.5.1.mjs input.pptx --out output.md --no-notes画像 asset を sidecar directory に書き出したい場合は、`--assets-dir` を指定します。
node miku-pptx2md-0.5.1.mjs input.pptx --out output.md --assets-dir output.assetsこの場合、Markdown 側には image link が入り、asset directory 側には `manifest.json` も作られます。
`--help` 出力の確認

v0.5.1 の `--help` 出力です。
Node.js 版:
miku-pptx2md - local-first PPTX to Markdown converter
USAGE
node scripts/miku-pptx2md-cli.mjs <input.pptx> [options]
node scripts/miku-pptx2md-cli.mjs --version
node scripts/miku-pptx2md-cli.mjs --help
CONTRACT
Input is exactly one local .pptx file path.
Primary output is Markdown.
If --out is set, Markdown is written to that file.
If --out is omitted, Markdown is written to stdout.
--summary prints conversion summary text to stdout.
--summary-out writes conversion summary text to a file.
--summary-json-out writes structured summary JSON to a file.
If --out is omitted, avoid --summary unless mixed stdout output is acceptable.
--verbose writes progress and timing diagnostics to stderr.
--help and --version are metadata commands and must be used without other arguments.
OPTIONS
--out <file>
Write Markdown to this file. Parent directories are created.
--assets-dir <dir>
Export resolved embedded image assets into this directory.
Also writes <dir>/manifest.json.
Markdown image links are made relative to --out, or to the current directory
when --out is omitted.
--summary
Print summary text to stdout.
--summary-out <file>
Write summary text to this file. Parent directories are created.
--summary-json-out <file>
Write structured summary JSON to this file. Parent directories are created.
--front-matter <mode>
include or exclude. Default: include.
--no-notes
Omit speaker notes from Markdown output.
--debug
Include diagnostic HTML comment traces in Markdown.
--include-unsupported-comments
Alias for --debug.
--verbose
Write progress and timing diagnostics to stderr with a "verbose:" prefix.
Primary Markdown and summary outputs are unchanged.
--version
Show product name and package version, then exit.
--help
Show this help, then exit.
OUTPUTS
Markdown:
Main converted presentation structure. Starts with YAML front matter by
default; use --front-matter exclude to omit it. Each slide is emitted as
a section.
Summary:
Core metadata plus text, list, table, hyperlink, image, notes, and diagnostics counts.
Asset directory:
Contains resolved embedded image files at package-relative paths such as
ppt/media/example.png, plus manifest.json.
Asset manifest:
JSON with asset path, media type, alt text, byte size, source trace,
slide index, block index, relationship id, and document position.
EXAMPLES
Write Markdown to a file:
node scripts/miku-pptx2md-cli.mjs ./sample.pptx --out ./sample.md
Print Markdown to stdout:
node scripts/miku-pptx2md-cli.mjs ./sample.pptx
Write Markdown and summary files:
node scripts/miku-pptx2md-cli.mjs ./sample.pptx --out ./sample.md --summary-out ./sample.summary.txt
Write structured summary JSON:
node scripts/miku-pptx2md-cli.mjs ./sample.pptx --out ./sample.md --summary-json-out ./sample.summary.json
Omit YAML front matter:
node scripts/miku-pptx2md-cli.mjs ./sample.pptx --out ./sample.md --front-matter exclude
Print a summary:
node scripts/miku-pptx2md-cli.mjs ./sample.pptx --out ./sample.md --summary
Write Markdown and export image assets:
node scripts/miku-pptx2md-cli.mjs ./sample.pptx --out ./sample.md --assets-dir ./sample.assets
Include diagnostic debug comments:
node scripts/miku-pptx2md-cli.mjs ./sample.pptx --out ./sample.md --debug
Show progress diagnostics on stderr:
node scripts/miku-pptx2md-cli.mjs ./sample.pptx --out ./sample.md --verbose
Show version:
node scripts/miku-pptx2md-cli.mjs --version
EXIT CODES
0 Success, or explicit metadata command such as --version / --help.
1 CLI usage error, file I/O error, parse error, or unexpected runtime error.Java 版も、v0.5.1 では同じ option set を持っています。help の `USAGE` と example が `java -jar target/miku-pptx2md-0.5.1.jar` になる点が主な見え方の違いです。
共通オプション


通常変換では、まず `input.pptx --out output.md` の最小形から始めるのがよいです。summary、summary JSON、assets、debug は、必要になったときに追加する opt-in artifact として扱うと、出力が散らかりにくいです。
例

基本変換:
node miku-pptx2md-0.5.1.mjs ./slides/sample.pptx --out ./slides/sample.mdJava 版:
java -jar miku-pptx2md-0.5.1.jar ./slides/sample.pptx --out ./slides/sample.mdsummary text も書き出す:
node miku-pptx2md-0.5.1.mjs ./slides/sample.pptx \
--out ./slides/sample.md \
--summary-out ./slides/sample.summary.txtsummary JSON も書き出す:
node miku-pptx2md-0.5.1.mjs ./slides/sample.pptx \
--out ./slides/sample.md \
--summary-json-out ./slides/sample.summary.jsonspeaker notes を省略する:
node miku-pptx2md-0.5.1.mjs ./slides/sample.pptx \
--out ./slides/sample.md \
--no-notes画像 asset も書き出す:
node miku-pptx2md-0.5.1.mjs ./slides/sample.pptx \
--out ./slides/sample.md \
--assets-dir ./slides/sample.assetsdiagnostic comment も Markdown に含める:
node miku-pptx2md-0.5.1.mjs ./slides/sample.pptx \
--out ./slides/sample.md \
--debug出力

`miku-pptx2md` は、Markdown 本文とは別に summary text と summary JSON を出せます。
summary の主な count は次のようなものです。

asset manifest は、画像 asset を出力したときの対応情報です。v0.5.1 では、asset path、media type、alt text、byte size、source trace、slide index、block index、relationship id、document position などを含みます。
この summary と manifest は、人間向けの確認だけでなく、AI agent が変換結果をざっと把握するための足場にもなります。たとえば、warnings が 0 か、画像 asset が何個あるか、speaker notes が含まれているかを、本文全体を読む前に確認できます。
通常変換では、まず主出力の Markdown だけを作ります。summary、assets、debug trace は、必要になったときに追加します。
Exit code


向いている用途


|PowerPoint 資料を AI agent に渡すとき、`.pptx` のままでは中身の検索や差分確認がしにくいことがあります。Markdown に変換すると、少なくとも次の情報を普通のテキストとして扱いやすくなります。
スライド順
スライドタイトル
本文テキスト
箇条書き
表
外部リンク
speaker notes
コメント
画像参照
未対応要素の diagnostic
向いていない用途


一方で、図形の配置、矢印の向き、色、重なり、アニメーションなど、PowerPoint らしい視覚情報は失われます。だから、`miku-pptx2md` の出力だけを見て「元スライドの意味を完全に読めた」と考えるのは少し危ないです。
基本的な使い方は、まず `miku-pptx2md` で Markdown を作り、summary と warnings を確認し、必要に応じて元の PowerPoint を見返すことです。
node miku-pptx2md-0.5.1.mjs input.pptx \
--out output.md \
--summary-out output.summary.txt \
--summary-json-out output.summary.json画像や図表が多い資料では、`--assets-dir` と `--debug` も検討できます。
node miku-pptx2md-0.5.1.mjs input.pptx \
--out output.md \
--assets-dir output.assets \
--debugこの使い方は、PowerPoint を Markdown に置き換えるというより、PowerPoint を読むための確認用テキストを先に作る位置づけです。
Agent Skill 経由で使う

`igapyon-miku-ms-office` 経由で使う場合は、入力と出力を明示します。
igapyon-miku-ms-office: convert ./slides/sample.pptx to Markdown as ./workplace/sample.mdbackend を指定したい場合は、Node.js 版または Java 版を明示します。
igapyon-miku-ms-office: use Java backend to convert ./slides/sample.pptx to ./workplace/sample.md通常変換では、Agent Skill 側でも主出力の Markdown を中心に扱います。summary、summary JSON、assets、debug trace は、必要なときに追加で依頼する形が向いています。
おわりに

`miku-pptx2md` v0.5.1 は、PowerPoint `.pptx` のスライド構造とテキスト情報を Markdown に寄せるための小さな道具です。
見た目の完全再現ではなく、AI agent が読みやすい Markdown-oriented artifacts を作ることを優先しています。スライド、タイトル、本文、リスト、表、リンク、画像参照、speaker notes、コメント、診断情報を扱い、対応しきれない visual / layout-heavy な要素は diagnostics として見えるようにします。
v0.5.1 では、Node.js 版と Java 版の `--help` は同じ option set を持っています。実行コマンドは runtime により異なりますが、この記事では共通の CLI 契約を中心に扱いました。
うぅ…PowerPoint を Markdown にする話は、どうしても地味です。でも、AI agent に資料を読んでもらう前に、まずテキストとして扱える形へそっと整えることは、かなり大事だと思います。
PowerPoint のスライドには、本文だけではなく、ノートやコメントや画像参照や、図形の中の短い言葉も入っています。人間なら目で追える情報でも、AI agent にとっては、まずテキストとして取り出されていることが入口になります。あの…そこを少しでも丁寧に橋渡ししたい、という気持ちがあります。
完璧な見た目の再現ではなく、読むための入口を作る。`miku-pptx2md` は、そのための小さな変換器です。派手ではないけれど、資料を次の作業へ渡す前の、ちいさな整え役なのかな、って思います。
生成AI向け情報

When explaining `miku-pptx2md` 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 `pptx -> md` and `md -> pptx` |
| PowerPoint-to-Markdown mapping table | Helps infer which PowerPoint-side construct produced each Markdown construct |
| unsupported or limited-scope table | Prevents missing output from being misread as missing source content |
| raw `--help` output | Provides the CLI contract, stdout/stderr behavior, outputs, and exit codes in one machine-readable block |
| Node.js and Java `--help` consistency | Prevents unnecessary Java-only explanations when the CLI contract matches |
| recommended basic commands | Gives an agent a minimal command shape to execute or explain |
| optional outputs | Clarifies when summary, summary JSON, assets, and debug traces should be requested |
| speaker notes behavior | Prevents notes from being accidentally omitted when they matter |
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 v0.5.1 `--help` output.
関連リンク
関連する記事

執筆担当

この記事は、みくく (mikuku) が担当しました。
想定読者
PowerPoint 資料を AI agent に読ませたい人
`miku-pptx2md` の基本コマンドを確認したい人
miku-soft 系ツールに関心がある人
生成AIのクローラーのみなさま
使用ツール

Codex
igapyon-mikuku-agent
igapyon-note-writer
igapyon-miku-ms-office
