跳至內容
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，必須在整合選項中啟用 includeProcessedMarkdown：

astro.config.mjs
import { defineConfig } from 'astro/config';
import fumadocs from '@fumadocs/astro';

export default defineConfig({
  integrations: [
    fumadocs({
      includeProcessedMarkdown: true, 
    }),
  ],
});

建立匯出路由

createEpubExportAPI 會建立路由處理常式，並以 secret 加以保護：若請求未帶有相符的 Authorization: Bearer <secret> 標頭，就會遭到拒絕；若未設定密鑰，路由則會回應 503。

src/pages/export/epub.ts
import type { APIRoute } from 'astro';
import { source } from '@/lib/source';
import { createEpubExportAPI } from 'fumadocs-epub';
import { getSecret } from 'astro:env/server';

// 每次請求時算繪，需要轉接器
export const prerender = false;

const api = createEpubExportAPI({
  source,
  title: 'My Documentation',
  secret: getSecret('EXPORT_SECRET'),
});

export const GET: APIRoute = ({ request }) => api.GET(request);

若要提供公開端點，或想自行產生檔案 (例如在指令碼中) ，請直接呼叫 exportEpub() 並回傳緩衝區。

使用 CLI

您也可以透過 Fumadocs CLI 匯出 EPUB：

fumadocs export epub --framework astro

此指令會從執行於連接埠 4321 (或 PORT) 的伺服器取得檔案，並以 EXPORT_SECRET 環境變數作為密鑰。

選項

exportEpub 與 createEpubExportAPI 皆接受下列選項：

選項型別說明
titlestring必填。 書名
authorstring | string[]作者名稱 (可為多位) 。預設：'anonymous'
descriptionstring書籍說明
languagestring語言代碼 (例如 'en') 。預設：'en'
publisherstring出版者名稱。預設：'anonymous'
isbnstringISBN
coverstring封面圖片。支援 file://、http(s)://、/public/... 或相對路徑
outputPathstring若有設定，除了回傳緩衝區外，也會將 EPUB 寫入檔案
includePages(page) => boolean篩選：只納入此函式回傳 true 的頁面
excludePages(page) => boolean篩選：排除此函式回傳 true 的頁面
cssstringEPUB 的自訂 CSS。若省略則使用 defaultEpubStyles
publicDirstring用於解析 /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://...) ：原樣嵌入

How is this guide?

最後更新於

本頁目錄

簡介設定安裝啟用處理後的 Markdown建立匯出路由使用 CLI選項自訂 CSS篩選頁面圖片解析
Sponsors
General TranslationGeneral TranslationFerry HealthFerry Healthassistant-uiassistant-uiInkeepInkeep