コンテンツへスキップ
Fumadocs

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 を有効にする必要があります。

source.config.ts
import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  docs: {
    postprocess: {
      includeProcessedMarkdown: true,
    },
  },
});

エクスポートルートを作成する

createEpubExportAPI はルートハンドラーを作成します。このルートは secret で保護されており、Authorization: Bearer <secret> ヘッダーが一致しないリクエストは拒否されます。また、シークレット自体が設定されていない場合、ルートは 503 を返します。

src/routes/export/epub.ts
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 はどちらも次のオプションを受け付けます。

オプション型説明
sourceLoaderOutput | () => Promise<LoaderOutput>必須。 loader() から得たソース、またはソースを返す関数
titlestring必須。 書籍のタイトル
authorstring | string[]著者名(複数指定可)。デフォルト: 'anonymous'
descriptionstring書籍の説明
languagestring言語コード(例: 'en')。デフォルト: 'en'
publisherstring出版社名。デフォルト: 'anonymous'
coverstring表紙画像。file://、http(s)://、/public/...、または相対パスを指定できます
outputPathstring指定すると、バッファを返すだけでなく EPUB をファイルにも書き出します
includePages(page) => booleanフィルター: この関数が true を返すページのみを含めます
excludePages(page) => booleanフィルター: この関数が true を返すページを除外します
getMarkdown(page) => string | undefinedページの Markdown。undefined の場合はスキップされます。デフォルト: page.data.getText('processed')
cssstringEPUB 用のカスタム CSS。省略した場合は defaultEpubStyles が使用されます
publicDirstring/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?