hono-decks 1.0.4 → 1.2.0

package/README.ja.md

@@ -4,7 +4,175 @@
 
 Hono と Cloudflare Workers 上で MDX のスライドを配信するためのライブラリです。ビルド時に MDX を TypeScript module へ変換し、Worker runtime ではファイルシステムや compiler を読み込みません。
 
-## Quick start
+## Hono＋Vite／HonoX：init で接続する
+
+既存のアプリに `hono-decks` をインストールし、構成に合わせて初期設定します。
+
+```sh
+npm install hono-decks
+
+# Hono＋Vite
+npx hono-decks init --framework hono
+
+# HonoX の場合はこちら
+npx hono-decks init --framework honox
+
+# 以後は既存のコマンドを使う
+npm run dev
+npm run build
+```
+
+どちらも、既存の Vite 設定を保持して自動コンパイルを登録し、
+`hono-decks.config.ts`、`src/decks.ts`、サンプルの
+`decks/welcome/deck.mdx` を作ります。生成ファイルがない状態からでも
+通常の `dev`／`build` だけで動き、手動 `compile` やビルドコマンドの変更は不要です。
+生成コードは Vite の仮想モジュールとして扱い、ファイルへ出力しません。Void 用のアダプターは必要ありません。
+
+| 構成 | アプリへの接続 |
+| --- | --- |
+| `--framework hono` | 既存の Hono エントリーにルーターを追加。既存のミドルウェアとルートを保持 |
+| `--framework honox` | `createApp()` に設定連動のルートを追加。既存のオプション、ページ、ミドルウェアを保持 |
+
+公開先は `/slides/welcome` です。同名の既存デッキがあれば、サンプルには
+空いている名前を選びます。既存の `.mdx`、コンポーネント、画像はそのまま使えます。
+
+Hono では、`src/index.ts`／`.tsx`／`.js`／`.mts`／`.mjs` または
+`src/app.ts`／`.tsx`／`.js` の候補が1つなら自動検出します。
+独自の場所にある場合や複数の候補がある場合は、
+`--entry src/server.ts` のように指定してください。
+自動接続は `const app = new Hono()` で作ったアプリを default export する形式に対応します。
+先行する catch-all／動的ルートなど、安全に接続できない構成ではファイルを変更せず、
+手動接続の案内を表示します。
+
+HonoX は標準の `app/routes` と、`app/server.ts` で `createApp()` を default export
+する構成に対応します。`init` は `src/honox-decks.ts` を作り、既存の
+`createApp()` オプションを包みます。HonoX の公開 `ROUTES` API に設定から
+ルートを追加するため、**公開パスは `mountPath` 一か所の変更で切り替わります**。
+ルート用ディレクトリを作成・改名する必要はありません。既存ルートと重なる場合はエラーにします。
+開発中の公開パス変更では、コンパイル後に Vite を自動で再起動してルートを切り替えます。
+生成する HonoX 接続ファイルには、`import.meta.glob` によるルート探索と
+`hono-decks/honox` の `withHonoXDecks()` 呼び出しだけを置きます。
+ルートの合成と衝突検査はパッケージが担当し、動的ルートや catch-all との衝突も検出します。
+この処理の修正は、アプリ側を再生成せずパッケージ更新で受け取れます。
+`createApp()` のオプション、ミドルウェア、明示的な `ROUTES` は保持します。
+`--config config/slides.ts` で設定ファイルの場所を変えることもできます。
+
+## Void：通常の dev／build で使う
+
+既存の Void アプリに hono-decks と対応する Hono Markdown アダプターを
+インストールし、初回だけ `init` を実行します。
+
+```sh
+npx hono-decks init --framework void --install
+npm run dev
+# 本番用のビルド
+npm run build
+```
+
+この連携には `void-plugin-hono-jsx@^0.5.0` の standalone compiler／client export
+が必要です。`--install` は対応範囲のアダプターを選びます。
+`--install` を省略する場合は、Markdown 用の任意 peer も必要です：
+`markdown-exit@^1.3.0 yaml@^2.9.1 markdown-it-container@^4.0.0 shiki@^4.5.0 @shikijs/transformers@^4.5.0`。
+動作確認した組み合わせは Void 1.1.11、Vite 8.3.4、Hono 4.13.13 です。
+
+`--install` は npm／pnpm／Yarn／Bun を packageManager または lockfile から判定し、
+不足する依存だけを追加します。互換性のない既存バージョンは自動更新せずエラーにします。
+Yarn は node_modules linker を対象とし、PnP は手動インストールを使ってください。
+依存を自分で管理する場合は `--install` を省略できます。ローカルでビルドしたアダプターは
+`--adapter /absolute/path/void-plugin-hono-jsx.tgz` で指定できます。
+アプリ設定の衝突はインストール前に検査し、インストール失敗時は接続ファイルを作りません。
+パッケージマネージャーによる依存・lockfileの変更は残る場合があります。
+
+`init --framework void` は、既存のルート `vite.config.*` の default export を
+`withHonoDecks()` で包み、次のファイルを作ります。
+
+- `hono-decks.config.ts`：公開パス `/slides`、入力先 `decks`、Hono Markdown の有効化
+- `src/decks.ts`：アプリ側で編集できる接続ファイル
+- `middleware/hono-decks.ts`：スライド配下のルーティング、Markdown の CSS、開発時の自動更新
+- `decks/welcome/deck.md` と `Counter.tsx`：`/slides/welcome` で開ける対話可能なサンプル
+
+既存の `welcome` デッキがある場合は、`welcome-2` などの空いている名前を選び、
+URL を表示します。既存の Markdown／MDX はそのまま保持します。
+
+サンプルを編集するか、`decks` に `.md`／`.mdx` を追加してください。
+既存の Vite の `dev`／`build` が自動でコンパイルします。生成ファイルが
+ない状態から起動する場合も、手動 `compile`、別の監視プロセス、
+`package.json` のコマンド変更は不要です。Vite が生成コードをメモリ上で扱うため、
+生成用ディレクトリや、その `.gitignore` 登録も不要です。
+既存の Void のエントリー、ルート、package scripts は保持します。
+公開パスは既存ルートと重ならないものを選び、必要に応じてアプリのアクセス制御を適用してください。
+
+書き込み前に依存パッケージと出力先の衝突を確認します。既存の接続ファイルは
+上書きせず、hono-decks の二重登録も行いません。ESM の default export で
+設定を返すオブジェクト、式、非同期関数に対応します。対応できない設定では
+ファイルを変更せず、`honoDecks()` を手動で登録する方法を表示します。
+`--config config/slides.ts` で設定ファイルの場所を変更できます。
+`--out`／`--generated` は、以下の汎用 init 向けのオプションです。
+
+## Markdown 内のクライアントコンポーネント
+
+Hono Markdown では、別の登録ファイルを作らず、本文の import から自動登録できます。
+
+```md
+<script>
+import Counter from "./Counter.tsx" with { island: "load" };
+</script>
+---
+title: Interactive slide
+---
+# デモ
+
+<Counter label="Count" initial="2" />
+```
+
+`Counter.tsx` は Hono JSX の default export です。`hono/jsx` の `useState` を使えます。
+island はサーバーで初期描画し、`load`／`visible`／`idle`／`media:(query)` の条件で
+ブラウザー上で動かします。`visible` はスライドがアクティブになってから監視します。
+CSS import はコンパイル時に回収し、SSR・印刷ページにも含めます。
+`useFrontmatter()` と `useMarkdownHeadings()` は各スライドの情報を返します。
+クライアントへ渡すメタデータに秘密情報を含めないでください。
+
+対応範囲は相対 TSX／JSX の default import と、文字列・真偽値のリテラル属性です。
+JSX 式、island タグの子要素、任意の script コードは未対応です。
+静的な部品は引き続き `with { component: "static" }` を使います。
+既存 MDX のクライアントコンポーネント登録方法は変わりません。
+
+## Vite の生成物と型チェック
+
+Hono＋Vite／HonoX／Void は、共通の `virtual:hono-decks` を入口にします。
+`init` が作る `src/decks.ts` は、この仮想モジュールへ接続します。
+
+```ts
+/// <reference types="hono-decks/vite-env" />
+import { decks } from "virtual:hono-decks";
+
+export { decks };
+```
+
+`decks` は `hono-decks.config.ts` を適用したコレクションです。
+`decks.router()`、`decks.paths()` などの API は従来どおり使えます。
+仮想モジュールには必要に応じて設定を適用する `createDecks(config)` もあります。
+型定義はパッケージに同梱しているため、初回の `dev`／`build` 前でも型チェックできます。
+
+通常は `decks/` の原稿・画像・部品と設定ファイルを編集します。
+Vite はコンパイル結果をメモリ上のモジュールとして読み込み、ビルド時にアプリへ取り込みます。
+`src/generated` の作成や直接 import、`build.outDir` の指定は不要です。
+明示的に設定した OGP メタデータキャッシュは、従来どおり保存します。
+設定から import した別ファイルも監視するため、公開パスなどを分けて管理できます。
+init の開発クライアントは Vite の `BASE_URL` を使います。ホストの開発サーバーが
+Vite の URL を処理する構成では、base に合わせた既存のアセット除外設定も保持してください。
+
+既存の Vite 接続ファイルが生成先を直接 import している場合も、プラグインが
+設定された出力先を仮想モジュールへ解決します。生成 TypeScript を参照する
+`.js` 拡張子の import も互換性を維持します。新しい接続では上記の固定の入口を推奨します。
+
+Vite 以外で使う CLI の `hono-decks compile` と `compileDecks()` は、
+従来どおり `build.outDir`／`out` へファイルを書き出します。
+コンパイル処理は両方式で共通です。実行環境にコンパイラーや Node のファイル操作は持ち込みません。
+
+## Hono／MDX の Quick start
+
+Vite を使う Hono／HonoX／Void アプリでは、以下の手動コンパイル手順ではなく、上記の init を使ってください。
 
 ```bash
 bun add hono hono-decks
@@ -197,7 +365,7 @@ decks/product/
       index.tsx
 ```
 
-`components/index.tsx` は server-side JSX component、`components/client/index.tsx` は browser で hydrate する component です。`theme.css` はその deck だけに適用されます。画像は compile 時に検出され、`mountPath` と slug を使った public URL に書き換えられます。
+`components/index.tsx` は server-side JSX component、`components/client/index.tsx` は browser で hydrate する component です。`theme.css` はその deck だけに適用されます。 テーマ未指定時は白背景と濃い文字色を使います。配色を変える場合は `theme.css` で `--hono-decks-background` と `--hono-decks-color` を合わせて指定してください。1920 × 1080 の固定キャンバス内では `px` や `rem` を使います。`vw` / `vh` はブラウザのズームに応じて内容の配置も変えてしまいます。画像は compile 時に検出され、`mountPath` と slug を使った public URL に書き換えられます。
 
 ## Embedding
 
@@ -243,7 +411,7 @@ export default defineDecksConfig({
 
 独自CDNを使う場合は `imagePath: ({ deck }) => \`https://cdn.example.com/${deck.slug}.png\`` のように resolver で上書きできます。`false` または未指定なら social metadata は出力しません。
 
-生成処理は core に含まれません。`examples/ogp` では `hono-decks/node` の `compileDecks()` が返す manifest を Satori + resvg へ渡し、1200×630 PNG を Workers Static Assets へ保存します。Satori / resvg は example だけの依存で、Browser Rendering binding は不要です。Satori は TTF / OTF / WOFF を読み込めますが WOFF2 は扱えないため、対象言語の font file を build script から明示的に渡してください。
+生成処理は core に含まれません。`examples/ogp` では `hono-decks/node` の `compileDecks()` が返すデッキのメタデータを Satori + resvg へ渡し、1200×630 PNG を Workers Static Assets へ保存します。Satori / resvg は example だけの依存で、Browser Rendering binding は不要です。Satori は TTF / OTF / WOFF を読み込めますが WOFF2 は扱えないため、対象言語の font file を build script から明示的に渡してください。
 
 `build.ogpCacheFile` は `@[card](...)` が参照する外部サイトのメタデータキャッシュです。viewer 自身の share image とは別機能です。
 
@@ -290,3 +458,53 @@ app.route("/internal-slides", decksRouter({ source, dev: true }));
 - `examples/minimal`: standalone Worker の最小構成
 - `examples/basic`: R2、Browser Rendering、custom routes、client components
 - `examples/honox`: HonoX integration
+
+## Node ビルド結果と失敗時の復旧
+
+`compileDecks()` の戻り値は `CompileDecksResult` です。出力先、生成された
+`decks.ts` のパス、各デッキのメタデータ、スライドのモジュールパスを返します。
+描画には、生成された `decks.ts` の `createDecks()` を使ってください。
+戻り値をそのまま `defineDecks()` へ渡すコードは変更が必要です。
+タイトル、警告、アセット、ノートを `result.decks` から読む処理は引き続き使えます。
+
+同期レンダラーは同期の描画関数を実行します。非同期の本文には非同期版を使うよう
+エラーで案内し、描画できないビルド結果を渡した場合も空表示にせずエラーにします。
+
+生成処理とクライアント資産のビルドが完了してから、生成ファイルと OGP キャッシュを
+反映します。反映中に失敗した場合は、直前の内容へ戻します。OS やプロセスの停止時の
+一括反映、複数プロセスの同時実行は保証しません。復元自体に失敗した場合は、
+復旧用ファイルを残し、その場所をエラーに表示します。
+
+## Markdownアダプター
+
+従来の `build.markdown: "void"` に加えて、ビルド時に読み込むアダプターを指定できます。
+
+```ts
+export default defineDecksConfig({
+  mountPath: "/slides",
+  router: { clientEntryAssetPath: "/_assets/client" },
+  build: {
+    root: "decks",
+    markdown: { adapter: "hono-decks/adapters/hono-markdown" },
+  },
+});
+```
+
+このブリッジは共通の `@ts-76/hono-markdown` を利用します。共通パッケージはVoid・Viteに依存しません。このアダプターを選ぶ場合はコンパイラー用peer dependenciesも導入します。
+既存の `markdown: "void"` は、既に導入したVoidアダプターの公開コンパイラーAPIでも引き続き動作します。
+`init --framework void --install` の導入手順、既存のdev／buildコマンドは変わりません。
+
+設定はサーバー実行時にも読み込むため、アダプターは文字列で指定し、Node用のfactoryを設定ファイルへimportしません。
+Hono＋Vite・HonoXは引き続きMDXが標準で、VoidやMarkdown用パーサーの追加は不要です。
+これらでMarkdownを使う場合は、共通パッケージとコンパイラー用peer dependenciesを導入し、上記ブリッジを選択します。
+Viteは仮想モジュールを利用し、既存の `hono-decks compile` はファイル出力を維持します。
+
+独自アダプターは `createMarkdownAdapter({ cwd, options })` をexportし、`read(source)`、非同期の
+`compile(source, { sourcePath })`、`client(islands)` を返します。型は `hono-decks/adapters/hono-markdown` からimportできます。
+スライド分割・メタデータ・アセット・ルーティング・表示中スライドの判定はhono-decksが担当し、Markdownの変換とislandのスケジュールはアダプターが担当します。
+同じVoidアプリにhonoxpressを組み込んでも、ドキュメントとスライドが互いの内部実装に依存する必要はありません。
+
+Hono＋Vite・HonoXのinitは、dev serverが標準で`.js`を除外するため、拡張子なしの
+`/_assets/client`を設定します。配信は既存アプリのミドルウェア・認可を通ります。
+既存CLI構成の標準パス`/_assets/client.js`は維持します。VoidなしのMarkdown実アプリ検証は、
+`HONO_MARKDOWN_PACKAGE`に共通パッケージのtarballを指定し、`node scripts/verify-vite-init.mjs`で実行できます。

package/README.md

@@ -4,9 +4,173 @@ English | [日本語](https://github.com/ts-76/hono-decks/blob/main/packages/dec
 
 hono-decks serves MDX slide decks from Hono applications and Cloudflare Workers. It compiles MDX into TypeScript modules at build time, so the Worker runtime does not load the filesystem or the compiler.
 
-## Quick start
+## Hono + Vite / HonoX: connect with init
+
+Install hono-decks in an existing app and choose its integration:
+
+~~~sh
+npm install hono-decks
+
+# Hono + Vite
+npx hono-decks init --framework hono
+
+# Use this instead for HonoX
+npx hono-decks init --framework honox
+
+# Keep using the app's existing commands
+npm run dev
+npm run build
+~~~
+
+Both modes preserve the existing Vite config while adding automatic compilation,
+create `hono-decks.config.ts`, `src/decks.ts`, and a sample
+`decks/welcome/deck.mdx`. Generated code stays in Vite virtual modules and is not written to disk.
+Normal `dev` and `build` work from a checkout without generated files. There is
+no manual `compile` step or package script change. Neither mode needs the Void adapter.
+
+| Mode | Application connection |
+| --- | --- |
+| `--framework hono` | Adds the router to the existing Hono entry, preserving its middleware and routes |
+| `--framework honox` | Adds a config-driven route to `createApp()`, preserving its options, pages, and middleware |
+
+Open `/slides/welcome`. Init chooses another sample name if an existing deck has
+that slug. Existing MDX decks, components, and images remain supported.
+
+Hono init detects a single `src/index.ts`, `.tsx`, `.js`, `.mts`, `.mjs`, or
+`src/app.ts`, `.tsx`, `.js` candidate. Use `--entry src/server.ts` for a custom
+entry or multiple candidates. Automatic connection supports a default-exported
+`const app = new Hono()`. It leaves files unchanged and explains manual mounting
+when earlier catch-all/dynamic routes or another app shape prevent a safe edit.
+
+HonoX init supports the standard `app/routes` layout and a default-exported
+`createApp()` call in `app/server.ts`. It creates `src/honox-decks.ts` and wraps
+the existing createApp options. The helper adds the deck route through the public
+HonoX `ROUTES` API, so **changing `mountPath` alone changes the public path**.
+There is no route directory to create or rename. Conflicts with existing routes
+are errors. A mount change during development automatically restarts Vite after
+compilation so route registrations switch together.
+The generated HonoX file owns only `import.meta.glob` route discovery and a
+call to `withHonoXDecks()` from `hono-decks/honox`. Route composition and conflict
+checks are supplied by the package, including dynamic and catch-all conflicts.
+Package updates therefore update this behavior without regenerating app code.
+Custom `createApp()` options, middleware, and explicit `ROUTES` are preserved.
+Both modes accept `--config config/slides.ts`.
+
+## Void: use your existing dev and build commands
+
+In an existing Void app, install hono-decks and a compatible Hono Markdown
+adapter, then initialize once:
+
+~~~sh
+npx hono-decks init --framework void --install
+npm run dev
+# Production build:
+npm run build
+~~~
+
+This integration requires `void-plugin-hono-jsx@^0.5.0` or a compatible adapter
+with the `/markdown/compiler` and `/markdown/client` exports. `--install` selects
+the supported adapter range. Without `--install`, also install the optional Markdown peers:
+`markdown-exit@^1.3.0 yaml@^2.9.1 markdown-it-container@^4.0.0 shiki@^4.5.0 @shikijs/transformers@^4.5.0`.
+The verified host versions are Void 1.1.11, Vite 8.3.4, and Hono 4.13.13.
+
+`--install` selects npm/pnpm/Yarn/Bun from packageManager or lockfiles and installs
+missing dependencies. Incompatible installed versions require an explicit update;
+existing scripts are preserved. Yarn requires its node_modules linker; use manual
+installation for PnP. Omit `--install` to manage dependencies yourself. To use a local adapter build, pass `--adapter /absolute/path/void-plugin-hono-jsx.tgz`.
+Conflicting app files are checked before installation. Installation failures do not
+write integration files; dependency and lockfile changes may remain.
+
+`init --framework void` wraps the default export in the existing root
+`vite.config.*` with `withHonoDecks()` and creates:
+
+- `hono-decks.config.ts`: `/slides` mount, `decks` source directory, Hono Markdown enabled
+- `src/decks.ts`: the app-owned facade
+- `middleware/hono-decks.ts`: complete slide subtree routing, Markdown CSS, and dev reload support
+- `decks/welcome/deck.md` and `Counter.tsx`: an interactive two-slide sample at `/slides/welcome`
+
+If a `welcome` deck already exists, init chooses `welcome-2` (or the next free
+name) and prints its URL, preserving the existing Markdown or MDX deck.
+
+Edit the sample or add `.md` and `.mdx` decks under `decks`. Your existing Vite
+`dev` and `build` commands perform compilation automatically, including from a
+checkout without generated files. No manual `compile`, extra watch process, or
+`package.json` script changes are needed. Generated code stays in memory, so no
+generated directory or ignore entry is needed. Existing Void entry points, routes, and package scripts are preserved.
+Choose a mount path that does not conflict with app routes; apply your app's
+access policy to the slide subtree when needed.
+
+The command checks dependencies and output conflicts before writing. It refuses
+to overwrite integration files or add a second hono-decks integration. It accepts
+ESM default-export config objects, expressions, and async config functions. For
+an unsupported config, it leaves files unchanged and explains how to register
+`honoDecks()` manually. `--config config/slides.ts` selects another config path;
+`--out` and `--generated` apply only to the generic init below.
+
+## Client components inside Markdown
+
+Island imports register their components automatically; no separate registry is needed.
+
+~~~md
+<script>
+import Counter from "./Counter.tsx" with { island: "load" };
+</script>
+---
+title: Interactive slide
+---
+# Demo
+
+<Counter label="Count" initial="2" />
+~~~
+
+Counter.tsx exports a default Hono JSX component and can use useState from hono/jsx.
+The initial HTML is rendered on the server. Hydration supports load, visible, idle,
+and media:(query); visible scheduling waits for the slide to become active.
+Imported CSS is compiled into deck styles, including SSR and print output.
+useFrontmatter() and useMarkdownHeadings() provide each slide's context on both
+server and client. Do not place secrets in metadata delivered to client islands.
+Only relative default TSX/JSX imports and literal string/boolean props are supported.
+JSX expressions, island tag children and arbitrary script code are unsupported.
+Static imports and the existing MDX client-component workflow remain available.
+
+## Vite modules and typechecking
+
+Hono + Vite, HonoX, and Void use the same `virtual:hono-decks` entry. Init creates
+an app-owned `src/decks.ts` facade connected to it:
+
+~~~ts
+/// <reference types="hono-decks/vite-env" />
+import { decks } from "virtual:hono-decks";
+
+export { decks };
+~~~
+
+`decks` is configured with `hono-decks.config.ts`; its `router()`, `paths()`, and
+other runtime APIs remain unchanged. The virtual module also exports
+`createDecks(config)` when another configured kit is needed. Bundled ambient types
+allow typechecking before the first dev or build run.
+
+Edit sources, images, components, and themes under `decks/`, plus your config.
+Vite reads compiled code from an in-memory module map and bundles it into the
+application. There is no `src/generated` directory to create or import and no
+need to set `build.outDir`. An explicitly configured OGP metadata cache is still
+written to disk. Imported config inputs (for example a separate mount-path
+settings file) are also watched. Init uses Vite's `BASE_URL` for its development
+client script. If the host's dev server intercepts Vite URLs, keep its existing
+asset exclusions configured for the chosen base.
+
+Existing Vite facades that import their configured generated path also resolve
+through the virtual graph, including `.js` imports that previously resolved to
+generated TypeScript files. Prefer the stable entry above for new integrations.
+
+The non-Vite CLI `hono-decks compile` and `compileDecks()` continue to write files
+to `build.outDir` / `out`. Both destinations use the same compiler. Compiler and
+Node filesystem code remain outside the application runtime.
+
+## Hono / MDX quick start
 
 The examples below use Bun. npm, pnpm, and Yarn are supported as well.
+For a Vite-hosted Hono, HonoX, or Void app, use its init flow above instead of this manual compilation flow.
 
 ~~~bash
 bun add hono hono-decks
@@ -203,7 +367,7 @@ decks/product/
       index.tsx
 ~~~
 
-<code>components/index.tsx</code> contains server-side JSX components. <code>components/client/index.tsx</code> contains components hydrated in the browser. <code>theme.css</code> applies only to that deck. Local images are detected during compilation and rewritten to public URLs based on the mount path and deck slug.
+<code>components/index.tsx</code> contains server-side JSX components. <code>components/client/index.tsx</code> contains components hydrated in the browser. <code>theme.css</code> applies only to that deck. Without a theme, slides use a white background and dark text. Customize `--hono-decks-background` and `--hono-decks-color` together in `theme.css`. Use `px` or `rem` within the fixed 1920 × 1080 canvas; viewport units change the composition when browser zoom changes. Local images are detected during compilation and rewritten to public URLs based on the mount path and deck slug.
 
 ## Embedding
 
@@ -249,7 +413,7 @@ export default defineDecksConfig({
 
 Override <code>imagePath</code> with a resolver when images are served from a separate CDN. Set Open Graph configuration to <code>false</code>, or omit it, to suppress social metadata.
 
-Image generation is intentionally not part of the core package. The <code>examples/ogp</code> recipe passes the manifest returned by <code>compileDecks()</code> from <code>hono-decks/node</code> to Satori and resvg, then stores 1200 by 630 PNG files in Workers Static Assets. Satori and resvg are example-only dependencies, and the recipe does not require Browser Rendering. Satori accepts TTF, OTF, and WOFF fonts but not WOFF2, so the build script must receive a font file that covers the target language.
+Image generation is intentionally not part of the core package. The <code>examples/ogp</code> recipe uses the deck metadata returned by <code>compileDecks()</code> from <code>hono-decks/node</code> to Satori and resvg, then stores 1200 by 630 PNG files in Workers Static Assets. Satori and resvg are example-only dependencies, and the recipe does not require Browser Rendering. Satori accepts TTF, OTF, and WOFF fonts but not WOFF2, so the build script must receive a font file that covers the target language.
 
 <code>build.ogpCacheFile</code> stores external site metadata used by <code>@[card](...)</code>. It is separate from the viewer's share image.
 
@@ -259,6 +423,7 @@ Image generation is intentionally not part of the core package. The <code>exampl
 - <code>hono-decks/advanced</code>: <code>defineDecks()</code>, <code>decksRouter()</code>, <code>deckContext()</code>, raw renderers, and other low-level pipeline APIs
 - <code>hono-decks/client</code>: browser hydration
 - <code>hono-decks/node</code>: the compiler and Node filesystem adapter
+- <code>hono-decks/honox</code>: shared HonoX route composition and conflict checks; no HonoX dependency is required by Hono-only apps
 - <code>hono-decks/vite</code>: Vite integration that compiles and watches decks during development
 - <code>hono-decks/cli</code>: the programmatic CLI runner
 
@@ -296,3 +461,76 @@ At this level, the application owns the mount path, source policy, and option me
 - <code>examples/minimal</code>: the smallest standalone Worker setup
 - <code>examples/basic</code>: R2, Browser Rendering, custom routes, and client components
 - <code>examples/honox</code>: HonoX integration
+
+## Void Hono Markdown
+
+Set `build.markdown: "void"` in `hono-decks.config.ts` to opt into `.md` decks
+alongside MDX. This requires `void-plugin-hono-jsx@^0.5.0` with its standalone compiler and client exports.
+See the [Void consumer fixture](https://github.com/ts-76/hono-decks/tree/main/fixtures/void-markdown)
+for package verification, Void middleware hosting, supported syntax and limitations.
+
+## Node build results and failure recovery
+
+`compileDecks()` returns `CompileDecksResult`, containing `outDir`,
+`routerModulePath` and deck build summaries. Each slide summary includes its
+`modulePath` and metadata. This result is not a renderable `DeckManifest`.
+Import `createDecks()` from the generated `decks.ts` for runtime routing.
+Custom build scripts reading titles, warnings, assets or notes can continue
+using `result.decks`; code passing the return value into `defineDecks()` must
+switch to the generated module.
+
+Synchronous renderers execute synchronous slide render functions and reject
+async bodies with guidance to use the async renderer. Both renderers reject
+build summaries without a renderable body instead of silently producing empty
+slides.
+
+The compiler completes slide generation, client bundling and OGP-cache
+serialization before publishing. It stages all files and restores overwritten
+files (including cache files) on a publication error. Application-owned files
+are preserved. This guarantees rollback on reported build failure, not
+crash-atomic publication or coordination between concurrent compiler processes.
+If rollback itself fails, the error lists retained recovery directories.
+
+## Markdown adapters
+
+The deck compiler accepts a build-only module reference as well as the existing
+`build.markdown: "void"` preset:
+
+```ts
+export default defineDecksConfig({
+  mountPath: "/slides",
+  router: { clientEntryAssetPath: "/_assets/client" },
+  build: {
+    root: "decks",
+    markdown: { adapter: "hono-decks/adapters/hono-markdown" },
+  },
+});
+```
+
+The Hono Markdown bridge uses `@ts-76/hono-markdown/compiler` and its browser
+runtime. The common package has no Void or Vite dependency. Install its optional compiler peers when selecting this adapter. Existing
+Void configurations continue to work with the adapter's public compiler API,
+including compatible earlier adapter versions. `init --framework void
+--install` retains the one-command setup and unchanged dev/build scripts.
+
+Keep the adapter reference in config as a string: config is also imported by the
+server runtime. The compiler loads adapters only during builds. Hono+Vite and
+HonoX continue to default to MDX without installing Void or Markdown peers.
+For Markdown in these hosts, install the common package and its compiler peers
+and select the bridge above. Vite uses virtual modules; `hono-decks compile`
+continues to emit files.
+
+Custom build adapters export `createMarkdownAdapter({ cwd, options })`, returning
+`read(source)`, asynchronous `compile(source, { sourcePath })`, and
+`client(islands)`. Types are exported from `hono-decks/adapters/hono-markdown`.
+The deck host owns splitting, metadata, assets, routing and the visible-slide
+hydration gate; Markdown compilation and island scheduling belong to the adapter.
+Document adapters such as honoxpress can use the same Markdown package in a Void
+app without importing deck internals or changing their route ownership.
+
+Hono+Vite/HonoX init selects the extensionless `/_assets/client` route because
+`@hono/vite-dev-server` excludes `.js` requests by default. The client still goes
+through the application's middleware and authorization. Existing standalone CLI
+configurations retain their default `/_assets/client.js` route. For local
+Markdown checks without Void, set `HONO_MARKDOWN_PACKAGE` to the common tarball
+and run `node scripts/verify-vite-init.mjs`.

package/dist/adapters/hono-markdown.d.ts

@@ -0,0 +1,39 @@
+import "hono";
+import "hono/jsx";
+import "hono/utils/html";
+//#region src/node/markdown-adapter.d.ts
+interface MarkdownIsland {
+  id: string;
+  modulePath: string;
+  hydrate: string;
+}
+interface DeckMarkdownAdapter {
+  read(source: string): {
+    frontmatter: Record<string, unknown>;
+    content: string;
+    script: string;
+  };
+  compile(source: string, input: {
+    sourcePath: string;
+  }): Promise<{
+    code: string;
+    headings: {
+      depth: number;
+      slug: string;
+      text: string;
+    }[];
+    clientCode: string;
+    islands?: MarkdownIsland[];
+  }>;
+  client(islands: MarkdownIsland[]): string;
+}
+//#endregion
+//#region src/adapters/hono-markdown.d.ts
+/** Node-only bridge. Existing Void configs retain their original compiler/runtime pair. */
+declare function createHonoMarkdownAdapter(cwd: string, legacy?: boolean, options?: Record<string, unknown>): Promise<DeckMarkdownAdapter>;
+declare function createMarkdownAdapter({ cwd, options }: {
+  cwd: string;
+  options?: Record<string, unknown>;
+}): Promise<DeckMarkdownAdapter>;
+//#endregion
+export { type DeckMarkdownAdapter, type MarkdownIsland, createHonoMarkdownAdapter, createMarkdownAdapter };

package/dist/adapters/hono-markdown.js

@@ -0,0 +1,47 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region src/adapters/hono-markdown.ts
+/** Node-only bridge. Existing Void configs retain their original compiler/runtime pair. */
+async function createHonoMarkdownAdapter(cwd, legacy = false, options) {
+	const require = createRequire(resolve(cwd, "package.json"));
+	const entry = legacy ? "void-plugin-hono-jsx/markdown/compiler" : "@ts-76/hono-markdown/compiler";
+	let compiler;
+	try {
+		compiler = await import(pathToFileURL(require.resolve(entry)).href);
+	} catch (cause) {
+		throw new Error(`Hono Markdown requires ${legacy ? "its public /markdown/compiler API" : "@ts-76/hono-markdown/compiler"} and Markdown peers installed in the app.`, { cause });
+	}
+	const read = compiler.readMarkdownModule ?? compiler.readStaticMarkdown;
+	const compile = compiler.compileMarkdownModule ?? compiler.compileStaticMarkdown;
+	if (typeof read !== "function" || typeof compile !== "function") throw new Error("Missing standalone compiler API");
+	const runtime = entry.startsWith("void-plugin") ? "void-plugin-hono-jsx/markdown/client" : "@ts-76/hono-markdown/client";
+	return {
+		read,
+		compile: (source, input) => compile(source, {
+			...input,
+			options
+		}),
+		client: (islands) => emitMarkdownClient(islands, runtime)
+	};
+}
+function createMarkdownAdapter({ cwd, options }) {
+	return createHonoMarkdownAdapter(cwd, false, options);
+}
+function emitMarkdownClient(islands, runtime) {
+	if (!islands.length) return "";
+	const literal = (value) => JSON.stringify(value).replace(/</g, "\\u003c");
+	return `import { hydrateMarkdownIslands } from ${literal(runtime)};
+hydrateMarkdownIslands({ ${islands.map((island) => `${literal(island.id)}: () => import(${literal(island.modulePath)})`).join(",")} }, {
+  ready(element, start) {
+    const slide = element.closest('section[data-slide-state]');
+    if (!slide || slide.dataset.slideState === 'active') { start(); return; }
+    const observer = new MutationObserver(() => {
+      if (slide.dataset.slideState === 'active') { observer.disconnect(); start(); }
+    });
+    observer.observe(slide, { attributes: true, attributeFilter: ['data-slide-state'] });
+  }
+});`;
+}
+//#endregion
+export { createHonoMarkdownAdapter, createMarkdownAdapter };

package/dist/advanced.d.ts

@@ -177,6 +177,8 @@ interface CompiledDeck {
   meta: DeckFrontmatter;
   themeStyle?: string;
   themeSourcePath?: string;
+  /** Omit generated client code for explicitly static compiled decks. */
+  clientEntryRequired?: boolean;
   slides: CompiledSlide[];
   assets: AssetRef[];
   componentRegistry?: Record<string, SlideComponentInput>;
@@ -542,9 +544,14 @@ interface DefinedDecks<E extends Env = any> {
 }
 /** File-system settings consumed by the CLI. */
 interface DecksBuildConfig {
+  /** Build-only Markdown adapter reference. "void" retains the compatible preset. */
+  markdown?: "void" | {
+    adapter: string;
+    options?: Record<string, unknown>;
+  };
   /** Deck source directory. @default "decks" */
   root?: string;
-  /** Generated module directory. @default "src/generated" */
+  /** CLI output directory. Vite keeps modules in memory. @default "src/generated" */
   outDir?: string;
   /** Optional deterministic Open Graph metadata cache. */
   ogpCacheFile?: string;