EPUB Book Export

Copyexport async function exportEpub<C extends LoaderConfig>(
  options: EpubExportOptions<C>,
): Promise<Buffer>

Copyexport interface EpubConfig<Config extends LoaderConfig = LoaderConfig> {
  /** Book title */
  title: string;
  /** Author name(s) */
  author?: string | string[];
  /** Book description */
  description?: string;
  /** Language code (e.g. 'en') */
  language?: string;
  /** Publisher name */
  publisher?: string;
  /** Cover image - URL, file path, or path relative to public dir */
  cover?: string;
  /** Output file path - if set, writes to file in addition to returning buffer */
  outputPath?: string;
  /** Filter: include only these pages. Applied first (only pages where includePages(page) === true are considered). */
  includePages?: (page: Config['page']) => boolean;
  /** Filter: exclude these pages. Applied after includePages (removes pages from the include-filtered set). */
  excludePages?: (page: Config['page']) => boolean;
  /** Custom CSS for the EPUB */
  css?: string;
  /** Public directory for resolving /public/... image paths */
  publicDir?: string;
}

Copyexport interface EpubExportOptions<
  Config extends LoaderConfig = LoaderConfig,
> extends EpubConfig<Config> {
  /** Fumadocs source (from loader()) */
  source: LoaderOutput<Config>;
  /** function to get page Markdown content */
  getMarkdown?: (page: Config['page']) => string | undefined | Promise<string | undefined>;
}

Copy// Get pages in tree order (navigation order)
const pageTree = source.getPageTree();
const orderedPages = getPagesInTreeOrder(pageTree, (node) => source.getNodePage?.(node)).filter(
  (p): p is Page => p != null,
);
 
// Fallback to getPages() if tree order yields no pages (e.g. i18n)
const pages = orderedPages.length > 0 ? orderedPages : source.getPages();
 

Copyexport function getPagesInTreeOrder<Page>(
  pageTree: PageTree.Root,
  getNodePage: (node: PageTree.Item) => Page | undefined,
): Page[] {
  const mainItems = flattenTree(pageTree.children);
  const fallbackItems = pageTree.fallback ? flattenTree(pageTree.fallback.children) : [];
  const items = [...mainItems, ...fallbackItems];
  const pages: Page[] = [];
 
  for (const item of items) {
    const page = getNodePage(item);
    if (page) {
      pages.push(page);
    }
  }
 
  return pages;
}

Copyconst filteredPages = pages.filter((page) => {
  if (includePages && !includePages(page)) return false;
  if (excludePages && excludePages(page)) return false;
  return true;
});
 
const chapters: { title: string; content: string }[] = [];
 
for (const page of filteredPages) {
  const markdown = await getMarkdown(page);
  if (!markdown) continue;
 
  const pageDir = getPageDir(page, cwd);
  const html = await markdownToHtml(markdown, pageDir, publicDir);
  const pageTitle = page.data.title ?? page.slugs[page.slugs.length - 1] ?? 'Untitled';
 
  chapters.push({
    title: pageTitle,
    content: html,
  });
}

Copyfunction getPageDir(page: Page, cwd: string): string {
  if (page.absolutePath) {
    return path.dirname(page.absolutePath);
  }
  return path.resolve(cwd, path.dirname(page.path));
}

Copyfunction resolveCoverPath(
  cover: string | undefined,
  cwd: string,
  publicDir?: string,
): string | undefined {
  if (!cover) return undefined;
  if (cover.startsWith('file://') || cover.startsWith('http://') || cover.startsWith('https://'))
    return cover;
  if (cover.startsWith('/')) {
    const base = publicDir ?? path.join(cwd, 'public');
    return pathToFileUrl(path.join(base, cover.slice(1)));
  }
  return pathToFileUrl(path.resolve(cwd, cover));
}

Copyconst exportCmd = program.command('export').description('export documentation to various formats');
 
exportCmd
  .command('epub')
  .description('export documentation to EPUB format (run after production build)')
  .requiredOption('--framework <name>', 'React framework: next, tanstack-start, react-router, waku')
  .option('--output <path>', 'output file path', 'docs.epub')
  .option('--scaffold-only', 'only scaffold the EPUB route, do not copy')
  .action(async (options: { output?: string; framework: string; scaffoldOnly?: boolean }) => {
    await exportEpub({
      output: options.output,
      framework: options.framework,
      scaffoldOnly: options.scaffoldOnly,
    });
  });

Copyasync function scaffoldEpubRoute(cwd: string): Promise<boolean> {
  const appDir = await findAppDir(cwd);
  if (!appDir) {
    console.error(picocolors.red('Could not find app directory (app/ or src/app/)'));
    return false;
  }
 
  const routePath = path.join(appDir, 'export', 'epub', 'route.ts');
  if (await exists(routePath)) {
    console.log(picocolors.yellow('EPUB route already exists at'), routePath);
    return true;
  }
 
  await fs.mkdir(path.dirname(routePath), { recursive: true });
  await fs.writeFile(routePath, API_ROUTE_TEMPLATE);
  console.log(picocolors.green('Created EPUB route at'), routePath);
  return true;
}

Copy// Check for fumadocs-epub dependency
if (!pkg) {
  console.error(
    picocolors.red('Cannot read or parse package.json. Ensure it exists and is valid JSON.'),
  );
  process.exit(1);
}
const deps = { ...pkg.dependencies, ...pkg.devDependencies };
if (!deps['fumadocs-epub']) {
  console.log(picocolors.yellow('\nInstalling fumadocs-epub...'));
  const packageManager = process.env.npm_execpath?.includes('pnpm')
    ? 'pnpm'
    : process.env.npm_execpath?.includes('bun')
      ? 'bun'
      : 'npm';
  const installCmd = `${packageManager} add fumadocs-epub`;
  try {
    await execAsync(installCmd, { cwd });
  } catch (err: unknown) {
    const stderr =
      err && typeof err === 'object' && 'stderr' in err
        ? String((err as { stderr?: string }).stderr)
        : '';
    console.error(picocolors.red(`Failed to install fumadocs-epub. Command: ${installCmd}`));
    if (stderr) console.error(stderr);
    process.exit(1);
  }
}
 
if (framework === 'next') {
  const secret = process.env.EXPORT_SECRET;
  if (!secret) {
    console.error(
      picocolors.red('EXPORT_SECRET is required for Next.js export. Set it in your environment.'),
    );
    process.exit(1);
  }