Fumadocs 与 Htmlpress 对比

更新于 2026年11月1日

Fumadocs 是一个基于 Next.js、围绕 App Router 构建的文档框架。它把职责拆分到多个独立的包中：fumadocs-core（无头逻辑）、fumadocs-ui（默认 UI 组件）和 fumadocs-mdx（内容源加载器）。

概览

维度	Htmlpress	Fumadocs
语言 / 运行时	Rust（单一二进制文件，无运行时）	TypeScript / Node 18+
UI 框架	无（纯 HTML + CSS，`htmlpress-*` Web 组件）	React 18/19（Next.js App Router）
构建工具	htmlpress 二进制文件	Next.js（Turbopack/Webpack）
内容格式	HTML 和 Markdown 页面	Markdown + MDX
许可证	MIT，自托管	MIT，自托管
输出模式	预渲染静态页面	静态或 SSR（Next.js 模式）

架构

htmlpress 是一个 Rust 二进制文件，可从 npm（gethtmlpress）、PyPI 或 crates.io 安装。它用一个布局包裹每个 HTML 页面，并配上导航和主题；没有打包器、没有 UI 框架，也没有插件 API。每个内置文件——布局、样式、脚本以及每个组件——都可以被覆盖：在 .htmlpress/ 下的相同路径放一个文件即可替换它。

Fumadocs 假定你已经有（或想要）一个 Next.js 应用。它不是一个自成一体的 CLI——你需要先搭建一个 Next 项目，安装 Fumadocs 的各个包，再把 fumadocs-core 和 fumadocs-ui 接入你的 App Router。内容由 fumadocs-mdx 从 .md/.mdx 文件中读取，并以带类型的对象形式提供。

这种拆包是有意为之：fumadocs-core 暴露不含 UI 的钩子和基础原语，因此项目无需 fork 就能把 fumadocs-ui 换成自定义 UI。

在 htmlpress 这边，内容布局不受约束：它按 glob 扫描（htmlpress.yaml 中的 include/exclude，默认扫描所有 .html 文件），页面的 URL 取决于它在 glob 基础目录下的文件路径，因此 docs/**/*.html 会把 docs/guide.html 发布在 /guide/。不要求存在 docs/ 文件夹。导航由文件夹结构和每个页面的 <meta name="order"> 构建；文件夹的 index.html 为其分组命名。Fumadocs 从单个配置好的内容目录读取（在 fumadocs-mdx 的源插件中定义）；路由由该根目录下的文件路径推导而来。

内容层面

Fumadocs 接受带 frontmatter 和内嵌 React 组件的 Markdown + MDX。它使用 fumadocs-mdx（一个自定义的 MDX 加载器），生成带 TypeScript 类型的内容对象，frontmatter 拥有完整的 IntelliSense 支持。自定义组件与你的 Next 应用代码放在一起。

htmlpress 页面是纯语义化 HTML，主题直接根据元素本身设置样式。更丰富的区块是 htmlpress-* 自定义元素（htmlpress-callout、htmlpress-tabs、htmlpress-filetree、htmlpress-cards 等），其 CSS 和 JS 只会链接到使用该标签的页面。项目可以通过 .htmlpress/components/<name>/<name>.html 添加自己的标签，它会在构建时替换该标签。

htmlpress 没有 frontmatter：页面的元数据就是它自己的 <head>——<title>、<meta name="description">、<meta name="order">、<meta name="layout"> 和 <meta name="image">；其他 <head> 标签会原样保留。Fumadocs 使用 frontmatter：title、description、icon、full。

功能矩阵

功能	Htmlpress	Fumadocs
版本管理	部分支持（每个版本一个分区或一次部署）	部分支持（通过独立的内容源）
国际化（i18n）	是（翻译、语言选择器、内置 7 种界面语言）	是（内置）
搜索	是（内置，客户端）	是（基于 Orama，可选 Algolia）
OpenAPI 渲染	否	是（`fumadocs-openapi`）
博客	否	否（使用 Next 路由）
更新日志	否	否
站点地图	是（需设置 `site`）	通过 Next.js 的 `sitemap.ts`
RSS	否	通过 Next.js 路由
主题	`.htmlpress/` 中的覆盖文件 + `--htmlpress-*` 令牌	替换 `fumadocs-ui` 或逐个组件覆盖
自定义路由	任意 `.html` 文件；额外布局放在 `.htmlpress/layouts/`	任意 Next App Router 页面
独立 CLI	是（`htmlpress build`）	否（使用 Next.js 命令）

输出与部署

htmlpress 会把每个页面写成 .htmlpress/build/ 中的静态 HTML，同时生成 robots.txt、设置了 site 时的 sitemap.xml、每个页面的 Markdown 副本、llms.txt，以及 .well-known/agent-skills/ 下的智能体技能。base 键可让站点在子路径下提供服务。各托管平台的指南见部署。

Fumadocs 沿用 Next.js 的输出模式：完全静态导出（output: 'export'）、SSG/SSR 混合，或完全动态。部署方式与 Next.js 支持的一致——默认目标是 Vercel，但任何 Node 托管平台或 Cloudflare Workers（通过 OpenNext）都可以。

另请参阅

编写——htmlpress 的 HTML 编写方式。
自定义——htmlpress 的配置键与覆盖文件。
对比——返回索引。

用 ❤ 和 Htmlpress 构建