匯出 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 皆接受下列選項：

選項	型別	說明
`title`	`string`	必填。書名
`author`	`string \| string[]`	作者名稱 (可為多位) 。預設：`'anonymous'`
`description`	`string`	書籍說明
`language`	`string`	語言代碼 (例如 `'en'`) 。預設：`'en'`
`publisher`	`string`	出版者名稱。預設：`'anonymous'`
`isbn`	`string`	ISBN
`cover`	`string`	封面圖片。支援 `file://`、`http(s)://`、`/public/...` 或相對路徑
`outputPath`	`string`	若有設定，除了回傳緩衝區外，也會將 EPUB 寫入檔案
`includePages`	`(page) => boolean`	篩選：只納入此函式回傳 `true` 的頁面
`excludePages`	`(page) => boolean`	篩選：排除此函式回傳 `true` 的頁面
`css`	`string`	EPUB 的自訂 CSS。若省略則使用 `defaultEpubStyles`
`publicDir`	`string`	用於解析 `/public/...` 圖片路徑的 public 目錄。預設：`./public`

createEpubExportAPI 另外多了兩個選項：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://...) ：原樣嵌入

簡介複製錨點連結

設定複製錨點連結

安裝複製錨點連結

啟用處理後的 Markdown複製錨點連結

建立匯出路由複製錨點連結

使用 CLI複製錨點連結

選項複製錨點連結

自訂 CSS複製錨點連結

篩選頁面複製錨點連結

圖片解析複製錨點連結

本頁目錄

簡介

設定