# Mintlify 与 Htmlpress 对比

> 自托管的开源站点构建工具与托管的商业文档 SaaS。

[Mintlify](https://mintlify.com) 是一个商业文档平台。内容以 MDX 形式在 Git 仓库中编写；Mintlify 负责托管渲染后的站点、搜索和分析。按编辑者数量计费，开源项目可使用免费套餐。

## 概览

| 维度       | Htmlpress                            | Mintlify                           |
| -------- | ------------------------------------ | ---------------------------------- |
| 语言 / 运行时 | Rust（单一二进制文件，无运行时）                   | 用 MDX 编写；运行时是 Mintlify 的托管技术栈（未公开） |
| UI 框架    | 无（纯 HTML + CSS，`htmlpress-*` Web 组件） | React（据 Mintlify 文档）               |
| 构建工具     | htmlpress 二进制文件                      | Mintlify CLI（预览）+ 托管构建             |
| 内容格式     | HTML 和 Markdown 页面                   | Markdown + MDX                     |
| 许可证      | MIT，自托管                              | 专有，仅限托管                            |
| 输出模式     | 预渲染静态页面                              | 托管在 Mintlify 的基础设施上                |

## 架构

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

Mintlify 是一个托管 SaaS。你把 MDX 和 `mint.json` 配置提交到 Git 仓库；每次推送时 Mintlify 拉取代码、构建，并通过 `<your-subdomain>.mintlify.app` 或自定义域名提供结果。构建流水线和运行时均由平台管理，用户无法自行安装。

在 htmlpress 这边，内容布局不受约束：它按 glob 扫描（`htmlpress.yaml` 中的 `include`/`exclude`，默认扫描所有 `.html` 文件），页面的 URL 取决于它在 glob 基础目录下的文件路径，因此 `docs/**/*.html` 会把 `docs/guide.html` 发布在 `/guide/`。不要求存在 `docs/` 文件夹。导航由文件夹结构和每个页面的 `<meta name="order">` 构建；文件夹的 `index.html` 为其分组命名。Mintlify 要求文件树与 `mint.json` 中的 `navigation` 块一致；路由与所配置内容根目录下的文件路径对应。

## 内容层面

Mintlify 接受带 frontmatter 和组件嵌入的 Markdown + MDX。它提供一组固定的组件（`<Card>`、`<Accordion>`、`<Tabs>`、`<Steps>` 等），供作者在 MDX 中组合使用。你不需要为文档 UI 编写自己的 React 组件——而是使用 Mintlify 提供的基础组件。

htmlpress 页面是纯语义化 HTML，主题直接根据元素本身设置样式。更丰富的区块是 `htmlpress-*` 自定义元素（`htmlpress-callout`、`htmlpress-tabs`、`htmlpress-filetree`、`htmlpress-cards` 等），其 CSS 和 JS 只会链接到使用该标签的页面。项目可以通过 `.htmlpress/components/<name>/<name>.html` 添加自己的标签，它会在构建时替换该标签。内置组件（`htmlpress-cards` + `htmlpress-card`、`htmlpress-tabs`、`htmlpress-filetree`）能实现同类 UI，并且每一个都可以被覆盖。

Mintlify 的 `mint.json` 在一个声明式文件中配置导航、品牌和集成。htmlpress 使用 `htmlpress.yaml` 进行站点级设置，每个页面则用自己的 `<head>` 进行页面级设置。

## 功能矩阵

| 功能          | Htmlpress                                  | Mintlify            |
| ----------- | ------------------------------------------ | ------------------- |
| 版本管理        | 部分支持（每个版本一个分区或一次部署）                        | 是（内置）               |
| 国际化（i18n）   | 是（翻译、语言选择器、内置 7 种界面语言）                     | 是（内置）               |
| 搜索          | 是（内置，客户端）                                  | 是（内置，AI 驱动）         |
| AI 聊天 / 智能体 | 否（智能体文件：`llms.txt`、Markdown 副本、技能）         | 是（内置）               |
| 分析          | 否（可通过 `head` 脚本自行接入）                       | 是（内置仪表盘）            |
| OpenAPI 渲染  | 否                                          | 是（内置）               |
| 博客          | 否                                          | 是（更新日志/新闻页面）        |
| 站点地图        | 是（需设置 `site`）                              | 是                   |
| RSS         | 否                                          | 是（更新日志订阅源）          |
| 主题          | `.htmlpress/` 中的覆盖文件 + `--htmlpress-*` 令牌  | 通过 `mint.json` 设置主题 |
| 自定义路由       | 任意 `.html` 文件；额外布局放在 `.htmlpress/layouts/` | 否（仅限内容）             |
| 自托管         | 是                                          | 否                   |

## 输出与部署

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

Mintlify 的部署由 Mintlify 负责。你不需要自己构建或托管输出；平台通过其 CDN 提供渲染后的站点，并配置 TLS、域名和预览。离开 Mintlify 意味着要重新编写内容或将其迁移到别处。

## 另请参阅

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