EPUB のエクスポート
ドキュメントを電子書籍リーダー向けの EPUB 形式でエクスポートします
はじめに
EPUB インテグレーションを使うと、Fumadocs のドキュメントを EPUB ファイルとしてエクスポートできます。読者は電子書籍リーダーやタブレット、各種 EPUB 対応アプリでドキュメントを手軽にダウンロードして読めるようになります。
MDX コンテンツを HTML に変換し、画像を解決したうえで、目次付きの標準規格に準拠した EPUB を生成します。
セットアップ
Fumadocs CLI を使うと、セットアップを自動で行えます。EXPORT_SECRET で保護されたエクスポート用のルートが作成され、includeProcessedMarkdown が有効になります。
npx @fumadocs/cli feature epubまたは、手動で設定する場合:
インストール
npm install fumadocs-epub処理済み Markdown を有効にする
EPUB エクスポートを利用するには、docs コレクションの設定で includeProcessedMarkdown を有効にする必要があります。
import { defineDocs } from 'fumadocs-mdx/config';
export const docs = defineDocs({
docs: {
postprocess: {
includeProcessedMarkdown: true,
},
},
});エクスポートルートを作成する
createEpubExportAPI はルートハンドラーを作成します。このルートは secret で保護されており、Authorization: Bearer <secret> ヘッダーが一致しないリクエストは拒否されます。また、シークレット自体が設定されていない場合、ルートは 503 を返します。
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
import { createEpubExportAPI } from 'fumadocs-epub';
const api = createEpubExportAPI({
source,
title: 'My Documentation',
secret: process.env.EXPORT_SECRET,
});
export const Route = createFileRoute('/export/epub')({
server: {
handlers: {
GET: ({ request }) => api.GET(request),
},
},
});公開エンドポイントにする場合や、(スクリプト内などで)ファイルを自前で生成する場合は、exportEpub() を直接呼び出してバッファーを返してください。
CLI を使用する
Fumadocs CLI を使って EPUB をエクスポートすることもできます。
fumadocs export epub --framework tanstack-startビルド出力からファイルをコピーするため、事前にプロダクションビルドを実行してください。
オプション
exportEpub と createEpubExportAPI はどちらも次のオプションを受け付けます。
| オプション | 型 | 説明 |
|---|---|---|
source | LoaderOutput | () => Promise<LoaderOutput> | 必須。 loader() から得たソース、またはソースを返す関数 |
title | string | 必須。 書籍のタイトル |
author | string | string[] | 著者名(複数指定可)。デフォルト: 'anonymous' |
description | string | 書籍の説明 |
language | string | 言語コード(例: 'en')。デフォルト: 'en' |
publisher | string | 出版社名。デフォルト: 'anonymous' |
cover | string | 表紙画像。file://、http(s)://、/public/...、または相対パスを指定できます |
outputPath | string | 指定すると、バッファを返すだけでなく EPUB をファイルにも書き出します |
includePages | (page) => boolean | フィルター: この関数が true を返すページのみを含めます |
excludePages | (page) => boolean | フィルター: この関数が true を返すページを除外します |
getMarkdown | (page) => string | undefined | ページの Markdown。undefined の場合はスキップされます。デフォルト: page.data.getText('processed') |
css | string | EPUB 用のカスタム CSS。省略した場合は defaultEpubStyles が使用されます |
publicDir | string | /public/... の画像パスを解決するための public ディレクトリ。デフォルト: ./public |
createEpubExportAPI では、さらに 2 つのオプションを指定できます。secret(必須。ルートを保護します)と filename(ダウンロード時のファイル名。デフォルトは docs.epub)です。
カスタム CSS
デフォルトの EPUB スタイルは、次のように上書きできます。
import { exportEpub, defaultEpubStyles } from 'fumadocs-epub';
const buffer = await exportEpub({
source,
title: 'My Docs',
author: 'Me',
css: `${defaultEpubStyles}
/* カスタムスタイルによる上書き */
body { font-size: 1.1em; }
`,
});ページのフィルタリング
includePages と excludePages を使用すると、エクスポートするドキュメントを指定できます。
const buffer = await exportEpub({
source,
title: 'My Docs',
author: 'Me',
// /docs/getting-started 配下のドキュメントのみを対象にする
includePages: (page) => page.path.startsWith('getting-started'),
// 特定のパスを除外する
excludePages: (page) => page.path === 'changelog',
});画像の解決
MDX 内の画像は自動的に解決されます。
- 相対パス (例:
./image.png) :ページファイルを基準に解決されます - パブリックパス (例:
/og.png) :publicディレクトリを基準に解決されます - リモート URL (例:
https://...) :そのまま埋め込まれます
How is this guide?
