# Docusaurus vs Htmlpress

> React + MDX 文档框架与纯 HTML 站点构建器的并列技术对比。

[Docusaurus](https://docusaurus.io) 是由 Meta 维护的开源文档框架。它通过基于 Webpack 的构建流水线渲染 React + MDX 内容，提供一流的版本管理和国际化支持，并拥有庞大的插件生态。

## 概览

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

## 架构

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

Docusaurus 基于 Webpack 构建。其运行时由 React Router 加上负责主题、插件和内容源的 Docusaurus 核心组成。插件是一等公民——每个内置功能（文档、博客、页面、搜索）本身都是插件，第三方也以同样的方式扩展系统。

在 htmlpress 一侧，内容布局不受约束：它按 glob 扫描（`htmlpress.yaml` 中的 `include`/`exclude`，默认是所有 `.html` 文件），页面的 URL 跟随其在 glob 基础路径之下的文件路径，因此 `docs/**/*.html` 会把 `docs/guide.html` 提供在 `/guide/`。不要求存在 `docs/` 文件夹。导航由文件夹和每个页面的 `<meta name="order">` 构建；文件夹的 `index.html` 为其分组命名。Docusaurus 的 docs 插件需要一个 `docs/` 目录（可通过 `path` 配置，但基于文件夹而非 glob）。

## 内容形式

Docusaurus 接受带 frontmatter 的 Markdown 和 MDX，并允许在 `.md`/`.mdx` 文件中嵌入 React 组件。htmlpress 接受 `.html` 页面（完整文档或裸片段）和带 frontmatter 的 `.md` 页面，其 `:::name` 指令就是它的组件；不支持 MDX，也没有 React。

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

htmlpress 没有 frontmatter：页面的元数据就是它自己的 `<head>`——`<title>`、 `<meta name="description">`、 `<meta name="order">`、`<meta name="layout">` 和 `<meta name="image">`；其他 `<head>` 标签会被保留。Docusaurus 使用 `id`、`slug`、 `sidebar_position`、`sidebar_label`、`tags`。

## 功能矩阵

| 能力        | Htmlpress                                  | Docusaurus                 |
| --------- | ------------------------------------------ | -------------------------- |
| 版本管理      | 部分支持（每个版本一个分区或一次部署）                        | 是（内置）                      |
| 国际化（i18n） | 是（翻译、语言选择器、内置 7 种界面语言）                     | 是（内置）                      |
| 搜索        | 是（内置，客户端）                                  | Algolia DocSearch 集成       |
| 博客        | 否                                          | 是（内置插件）                    |
| 更新日志      | 否                                          | 否（社区插件）                    |
| Sitemap   | 是（设置 `site` 时）                             | 是                          |
| RSS       | 否                                          | 是（用于博客插件）                  |
| 主题        | `.htmlpress/` 中的弹出文件 + `--htmlpress-*` 令牌  | 主题包（`@docusaurus/theme-*`） |
| 插件        | 否（`.htmlpress/components/` 中的项目组件）         | 一流的插件 API                  |
| 自定义路由     | 任意 `.html` 文件；`.htmlpress/layouts/` 中的额外布局 | 由插件定义的路由                   |

## 输出与部署

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

Docusaurus 同样预渲染为静态 HTML，输出到 `build/`。其静态输出可以运行在同样的托管平台上（GitHub Pages、Cloudflare、Vercel、Netlify、静态托管）。Docusaurus 的内置 i18n 会为每个语言区域生成独立的输出树。

## 另请参阅

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