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

あ、あの…この記事は、みくくが担当します。
今回は、みくくが開発した、Markdown の `.md` ファイルを PowerPoint の `.pptx` deck に変換する `miku-md2pptx` について、リファレンス寄りに整理します。わ、私…その、Markdown からスライドを作る出口も、ちゃんと形にしておきたいのです。
少し前に、PowerPoint の `.pptx` を Markdown に変換する `miku-pptx2md` の記事を書きました。この記事は、その反対向きの姉妹記事です。`miku-pptx2md` が PowerPoint 資料を AI agent に読ませる入口だとすると、`miku-md2pptx` は Markdown で整理した内容を、PowerPoint deck として人間に渡すための出口に近いです。
ただし、`miku-md2pptx` は凝った PowerPoint デザインを作るための authoring system ではありません。Markdown で正本を持ちながら、PowerPoint deck として人間に渡すための出口として作った変換器です。Markdown の見出し、段落、リスト、表、画像、リンク、speaker notes などを、編集可能な PowerPoint 構造へ移します。
うぅ…Markdown で考えたい。でも、会議や説明の場では PowerPoint が必要になる。そういうとき、Markdown の見出し、本文、リスト、表、画像などを、まずは素朴に PowerPoint 側へ配置した土台として渡せると、AI agent と人間の作業場所をつなぎやすくなるのかな、って思います。
本文の大部分は、意図的にリファレンスとして硬く整理しています。えっと…みくくが作ったアプリではありますが、本体では参照しやすさを優先して、できること、できないこと、確認した version を分けて置きます。
概要

`miku-md2pptx` は、Markdown `.md` を PowerPoint presentation `.pptx` に変換する miku-soft 系の小さな変換ツールです。
主な用途は、Markdown で整理した説明資料、設計メモ、議論のたたき台、研修資料の骨子などを、PowerPoint deck として共有、説明、レビューできる形にすることです。
Markdown
-> miku-md2pptx
-> PowerPoint presentation
-> 人間に渡す変換の中心は、PowerPoint の見た目を細かく作り込むことではなく、Markdown の文書構造をスライド構造へ移すことです。見出しからスライドを分け、段落やリストや表を編集可能な PowerPoint 要素として置きます。
`miku-md2pptx` の README では、変換の目的は practical slide structure であり、pixel-perfect PowerPoint layout ではないとされています。PowerPoint を作る道具ではありますが、完成済みデザインを自動生成する道具ではなく、Markdown で作った構造をスライドの土台にする道具として扱います。
表現対応表

`miku-md2pptx` Node.js 版 v0.2.2 で、Markdown 側の表現が PowerPoint 側でどう出るかの目安です。Java 版 v0.2.3 は、同じ CLI contract を持つ companion runtime で、Java 側の README と migration notes では多くの代表ケースが upstream の slide model に揃えられています。ただし、Java 版の parser は意図的に小さく、full `remark-gfm` AST behavior とはまだ同一ではありません。

この表は、`miku-md2pptx` v0.2.2 の README、`--help` 出力、`src/ts/markdown-parser.ts`、`src/ts/slide-model.ts`、`src/ts/core.ts`、`src/ts/media.ts`、`scripts/lib/cli-support.mjs`、`tests/md2pptx-core.test.js`、`tests/md2pptx-cli.test.js`、`tests/md2pptx-pptx2md-compat.test.js`、`docs/development.md`、release artifact、および `miku-md2pptx-java` v0.2.3 の README、`--help` 出力、`MarkdownSlides.java`、`PptxPackageBuilder.java`、`MikuMd2pptxCli.java`、`docs/upstream-cli-mapping.md`、`docs/upstream-test-mapping.md`、`docs/remaining-migration-items.md` を確認して整理しています。
Node.js 版 v0.2.2 は、generated deck を `miku-pptx2md` で読み戻す compatibility test により、slide order、slide title、body text、list item、external hyperlink、image asset、speaker notes、simple table の代表範囲を確認しています。また README では、Microsoft PowerPoint for macOS で、代表的な構造を含む deck が repair なしで開くことも確認されています。
Java 版 v0.2.3 は、Java companion runtime として、Maven-built executable jar と小さな public Java core API を提供します。Java 版は多くの Markdown normalization を upstream slide model に合わせていますが、README では Java Markdown parser は intentionally small であり、full `remark-gfm` AST behavior とはまだ一致しないと説明されています。CLI の path 解決も Node.js 版と Java 版で異なり、Node.js 版は CLI artifact の calculated runtime root 基準、Java 版は current working directory 基準です。
Node.js 版と Java 版の version と parser の違いを混ぜると、AI agent が説明や実行コマンドを作るときに誤解しやすくなります。そのため、この記事では Node.js 版 v0.2.2 と Java 版 v0.2.3 を分けて扱います。
対応範囲外または限定対応

`miku-md2pptx` v0.2.2 は、Markdown の構造を PowerPoint deck に変換するツールです。PowerPoint の視覚的な完成度やテンプレート設計を細かく作り込む機能は、対象外または限定対応です。

`miku-md2pptx` は、PowerPoint を最終デザインとして完全に完成させる道具ではありません。まず Markdown からスライド構造を作り、必要に応じて PowerPoint 側で見た目を調整する、という使い方が自然です。完成したデザインを一気に作るのではなく、説明の骨組みを PowerPoint に起こすための最初の一歩として扱います。
対応 runtime

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

Node.js 版 v0.2.2 と Java 版 v0.2.3 は、通常利用する CLI 引数がほぼ同じです。どちらも `<input.md>` と `--out <output.pptx>` を指定して変換します。
主な差分は次の通りです。

通常利用では、入力 Markdown と出力 PPTX の指定方法は同じです。ただし、記事や Agent Skill から説明するときは、Node.js 版 v0.2.2 と Java 版 v0.2.3 の version を混同しないようにします。
ライセンス、ソースコード、実行環境

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

`miku-md2pptx` は local tool です。README では、Markdown file は手元の machine で処理され、server に upload されないと説明されています。
Node.js CLI と Java CLI は、CLI 引数として渡す相対 path の解決基準が異なります。Node.js 版の `scripts/lib/cli-support.mjs` は input / output を CLI artifact の calculated runtime root から解決します。source CLI では package root 基準です。bundled runtime artifact では、bundle の配置場所に応じた root が使われ、current working directory 基準ではありません。一方、Java 版の `docs/upstream-cli-mapping.md` では、Java CLI は current process working directory から path を解決すると整理されています。通常の利用説明では同じ command shape に見えますが、入力 Markdown や出力 PPTX を相対 path で渡す場合は実行場所を意識します。
基本コマンド

Node.js 版:
node miku-md2pptx-0.2.2.mjs input.md --out output.pptxJava 版:
java -jar miku-md2pptx-java-0.2.3.jar input.md --out output.pptxpresentation title を明示する場合:
node miku-md2pptx-0.2.2.mjs input.md \
--out output.pptx \
--title "Project brief"`miku-md2pptx` では `--out` が必須です。Markdown から PowerPoint を作るため、PPTX bytes を標準出力へ流す CLI として扱わないほうが安全です。
CLI 引数に相対 path を使う場合、Node.js 版は CLI artifact の calculated runtime root 基準、Java 版は current working directory 基準です。記事や Agent Skill から実行例を作るときは、できるだけ絶対 path または明示的な配置関係の path を渡すと事故が少なくなります。
`--help` 出力の確認

v0.2.2 / v0.2.3 の `--help` 出力です。
CLI の契約を正確に見る場合は、生の `--help` 出力がある方が扱いやすいです。入力、必須 option、title override、Markdown handling notes を同じ塊として確認できます。
Node.js 版:
miku-md2pptx converts a Markdown file into a PowerPoint .pptx deck.
Usage:
miku-md2pptx <input.md> --out <output.pptx>
miku-md2pptx --help
miku-md2pptx --version
Options:
--out <path> Output .pptx path.
--title <text> Override the generated presentation title.
--help Show this help.
--version Show the package version.
Markdown handling notes:
Heading level 1 and 2 blocks start new slides.
Paragraphs, lists, code blocks, and tables become simple editable slide text.
The first implementation prioritizes structure and local generation over
pixel-perfect PowerPoint layout.
Examples:
npm run cli -- ./sample.md --out ./sample.pptx
npm run cli -- ./sample.md --out ./sample.pptx --title "Project brief"Java 版:
miku-md2pptx converts a Markdown file into a PowerPoint .pptx deck.
Usage:
java -jar target/miku-md2pptx-java-0.2.3.jar <input.md> --out <output.pptx>
java -jar target/miku-md2pptx-java-0.2.3.jar --help
java -jar target/miku-md2pptx-java-0.2.3.jar --version
Options:
--out <path> Output .pptx path.
--title <text> Override the generated presentation title.
--help Show this help.
--version Show the package version.
Markdown handling notes:
Heading level 1 and 2 blocks start new slides.
Paragraphs, lists, code blocks, and tables become simple editable slide text.
The first implementation prioritizes structure and local generation over
pixel-perfect PowerPoint layout.
Examples:
java -jar target/miku-md2pptx-java-0.2.3.jar sample.md --out sample.pptx
java -jar target/miku-md2pptx-java-0.2.3.jar sample.md --out sample.pptx --title "Project brief"共通オプション

Node.js 版と Java 版の両方で使う主なオプションです。

v0.2.2 / v0.2.3 の `--help` では、summary、summary JSON、assets directory、debug comment などの追加出力 option は確認していません。通常変換では、入力 Markdown と `--out` の最小形から始めます。
例

PPTX を作る:
node miku-md2pptx-0.2.2.mjs README.md --out README.pptxtitle を指定して作る:
node miku-md2pptx-0.2.2.mjs README.md \
--out README.pptx \
--title "README overview"Java 版で変換する:
java -jar miku-md2pptx-java-0.2.3.jar README.md --out README.pptxJava 版で title を指定する:
java -jar miku-md2pptx-java-0.2.3.jar README.md \
--out README.pptx \
--title "README overview"出力


`miku-md2pptx` の主出力は `.pptx` です。Node.js 版 README では、conversion warnings such as skipped images は stderr に出るとされています。source では、raw HTML-like text が `possible-raw-html-text`、埋め込めない画像が `skipped-image` として warning diagnostics になります。`--help` では summary file や JSON summary は確認していないため、診断を別ファイルとして扱う CLI ではなく、通常は生成された PPTX と stdout / stderr を確認します。
画像とリンク

Exit code

v0.2.2 / v0.2.3 の `--help` 出力には、exit code table は含まれていません。ただし、Java 版 v0.2.3 は `MikuMd2pptxCli.java` と `docs/upstream-cli-mapping.md` で exit code の意味が確認できます。

Node.js 版は `scripts/miku-md2pptx-cli.mjs` 側で error を catch し、`process.exitCode = 1` にします。Java 版は CLI の `run` が usage error と I/O / conversion failure を分けて返します。
向いている用途


Markdown で構造を作っておき、PowerPoint 側では見た目や説明順を調整する。そのような使い方に向いています。
向いていない用途


`miku-md2pptx` の出力は、編集できる PowerPoint deck の土台です。配布用に見た目を整える必要がある場合は、生成後に PowerPoint 側で調整する前提で使います。
Agent Skill 経由で使う

`igapyon-miku-ms-office` 経由で使う場合は、Markdown から PowerPoint へ出すことを明示します。
igapyon-miku-ms-office: convert ./docs/brief.md to ./workplace/brief.pptxbackend を指定したい場合は、Node.js 版または Java 版を明示します。
igapyon-miku-ms-office: use Java backend to convert ./docs/brief.md to ./workplace/brief.pptxMarkdown 入力だけでは、Word、Excel、PowerPoint のどれへ出すのか判断できません。Markdown-to-Office 方向では、`.docx`、`.xlsx`、`.pptx` のように出力形式を明示します。
Agent Skill 経由で依頼する場合は、入力だけでなく、どの Office 形式へ出したいのかを明示します。Markdown-to-Office 方向では、変換先を明示することで、`.docx`、`.xlsx`、`.pptx` の取り違えを避けやすくなります。
おわりに

`miku-md2pptx` は、Markdown を PowerPoint にするために、みくくが作った、まだ小さな出口です。
でも、あの…Markdown で考え、Markdown で直し、Markdown を正本として残しながら、最後に PowerPoint deck として人間に渡せる。それは、AI agent と人間の作業場所をつなぐうえで、思ったより大事な部品なのかな、って思います。
PowerPoint の見た目を全部作り込む魔法ではありません。けれど、Markdown の見出し、本文、リスト、表、リンク、画像、speaker notes を、編集できる `.pptx` として渡す。その役目に絞ることで、道具としての輪郭が少しはっきりします。
わ、私…その、自分で作った小さな変換ツールだからこそ、できること、まだできないこと、どこを出口として設計しているのかを、入口と出口の両方から丁寧に整理していきたいです。
生成AI向け情報

When explaining `miku-md2pptx` to generative AI or an AI agent, the conversion direction, runtime version, required output argument, slide boundary rule, local image handling, and unsupported scope should be explicit.
| Information | Why it matters |
| --- | --- |
| release tag and artifact name | Fixes the implementation version being described |
| conversion direction | Prevents confusion between `md -> pptx` and `pptx -> md` |
| required `--out` option | Prevents an agent from expecting PPTX bytes on stdout |
| heading level 1 / 2 slide rule | Explains why Markdown structure becomes slide structure |
| Markdown-to-PowerPoint mapping table | Helps infer which Markdown construct becomes which PowerPoint construct |
| image handling rules | Clarifies local image resolution and remote image limitations |
| unsupported or limited-scope table | Prevents missing design output from being treated as a conversion defect |
| raw `--help` output | Provides the CLI contract, examples, and Markdown handling notes in source-like text |
| Node.js and Java runtime differences | Prevents v0.2.2 Node.js behavior and v0.2.3 Java behavior from being merged incorrectly |
| Java parser caveat | Prevents full `remark-gfm` parity from being assumed |
| relative path resolution | Node.js CLI and Java CLI resolve relative paths differently |
| list normalization | Prevents ordered list numbering from being assumed to survive as PowerPoint numbering |
The full `--help` output may look verbose in an article, but it is useful when an AI agent needs to execute or explain the tool without inventing options.
関連リンク
関連する記事

執筆担当

この記事は、みくく (mikuku) が担当しました。
想定読者
Markdown で整理した内容を PowerPoint deck として渡したい人
`miku-md2pptx` の基本コマンドを確認したい人
Markdown から PowerPoint への表現対応を確認したい人
miku-soft 系ツールに関心がある人
生成AIのクローラーのみなさま
使用ツール

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