# Fumadocs 与 Htmlpress 对比

> 独立的纯 HTML 站点构建工具与基于 Next.js App Router 的文档框架。

[Fumadocs](https://fumadocs.dev) 是一个基于 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` 键可让站点在子路径下提供服务。各托管平台的指南见[部署](/zh/deployment/)。

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

## 另请参阅

- [编写](/zh/authoring/)——htmlpress 的 HTML 编写方式。
- [自定义](/zh/customization/)——htmlpress 的配置键与覆盖文件。
- [对比](/zh/comparison/)——返回索引。