GitBook 与 Htmlpress 对比
GitBook
是一个商业化的托管文档平台。内容在基于浏览器的块编辑器（Notion 风格）中编写，存放在
GitBook 的数据库里，并发布到托管在 GitBook 上的站点，位于
gitbook.io 之下或自定义域名。Git Sync 功能可以把该数据库以 Markdown
形式与 GitHub/GitLab 仓库双向同步，但唯一可信的来源是 GitBook 本身，而不是仓库。
早期开源的 gitbook-cli 静态生成器已于 2018
年弃用，与如今的产品无关；本页介绍的是当前的托管平台。
概览
| 维度 | Htmlpress | GitBook |
|---|---|---|
| 语言 / 运行时 | Rust（单一二进制文件，无运行时） | 托管 SaaS（无本地运行时） |
| UI 框架 | 无（纯 HTML + CSS，htmlpress-* Web 组件） |
专有（由 GitBook 渲染） |
| 构建工具 | htmlpress 二进制文件 | 无（用户侧无需构建） |
| 内容格式 | HTML 和 Markdown 页面 | 编辑器中的块模型；通过 Git 使用 GitBook 风格的 Markdown |
| 许可证 | MIT，自托管 | 专有；免费套餐 + 付费套餐；仅 Enterprise 版可自托管 |
| 输出模式 | 预渲染静态页面 | 托管在 GitBook 的基础设施上 |
架构
htmlpress 是一个 Rust 二进制文件，可从 npm（gethtmlpress）、PyPI 或
crates.io 安装。它用一个布局包裹每个 HTML 页面，并配上导航和主题；没有打包器、没有
UI 框架，也没有插件
API。每个内置文件——布局、样式、脚本以及每个组件——都可以被覆盖：在
.htmlpress/
下的相同路径放一个文件即可替换它。页面就是你仓库中的文件，并在构建时预渲染为静态
HTML。
GitBook 是一个多租户 SaaS。内容在基于块的所见即所得编辑器中编写：每个段落、标题、代码块、提示或嵌入内容都是一个有类型的块，存储在 GitBook 的数据库中。运行时是 GitBook 自己的——用户无需运行构建步骤，也不用部署静态站点。托管、搜索索引、CDN、重定向和分析都由平台管理。
Git Sync 是一项可选集成，它把一个 GitBook 空间映射到 GitHub 或 GitLab
仓库的某个分支。内容在编辑器与一个由 .md
文件组成的目录之间往返同步，这些文件使用 GitBook 扩展的 Markdown 风格（用
{% hint %} 表示的提示、标签页、内容引用、OpenAPI
块等）。同步是双向的：在编辑器中的编辑会向仓库推送提交；推送到该分支的提交会更新编辑器。仓库只是镜像，而非来源——GitBook
的模式才是权威模型。
在 htmlpress 这边，内容布局不受约束：它按 glob 扫描（htmlpress.yaml
中的 include/exclude，默认扫描所有
.html 文件），页面的 URL 取决于它在 glob 基础目录下的文件路径，因此
docs/**/*.html 会把 docs/guide.html 发布在
/guide/。不要求存在 docs/
文件夹。导航由文件夹结构和每个页面的
<meta name="order"> 构建；文件夹的
index.html 为其分组命名。GitBook 的内容按照产品固定的层级组织——组织 → 集合 → 空间 → 页面——站点 URL 由这棵树推导而来。Git Sync 镜像以嵌套目录的形式反映这一层级。
内容层面
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> 标签会原样保留。
GitBook
的内容层面就是编辑器的块面板：段落、标题、列表、表格、提示（info/warning/danger/success）、标签页、可展开块、带标签分组的代码块、文件、图片、绘图、数学公式（KaTeX）、嵌入内容（Figma、Loom
等）、API 方法块、OpenAPI
参考以及内容引用（跨空间嵌入）。自定义组件无法由用户扩展——GitBook
提供什么块就只能用什么块。Git Sync 风格的 Markdown 通过类似 Liquid 的标签来编码
CommonMark 中没有的块，例如
{% hint style="info" %}…{% endhint %} 和
{% tabs %}…{% endtabs %}。
OpenAPI 是一等输入：GitBook 可以导入 OpenAPI 规范并据此渲染 API 参考页面，这一点更接近 Mintlify，而不是 htmlpress。
功能矩阵
| 功能 | Htmlpress | GitBook |
|---|---|---|
| 版本管理 | 部分支持（每个版本一个分区或一次部署） | 是（空间变体 / 版本组） |
| 国际化（i18n） | 是（翻译、语言选择器、内置 7 种界面语言） | 是（空间的按语言变体） |
| 搜索 | 是（内置，客户端） | 是（托管，付费套餐提供 GitBook AI / “Lens” 问答） |
| 博客 | 否 | 否 |
| 更新日志 | 否 | 否（Change Requests 是编辑工作流，而非对外发布的栏目） |
| 站点地图 | 是（需设置 site） |
是（由平台生成） |
| RSS | 否 | 否 |
| 主题 | .htmlpress/ 中的覆盖文件 + --htmlpress-* 令牌 |
通过站点设置自定义（颜色、字体、布局）；不支持模板覆盖 |
| 插件 | 否（使用 .htmlpress/components/ 中的项目组件） |
专有集成（Intercom、Segment、GA 等） |
| 自定义路由 |
任意 .html 文件；额外布局放在 .htmlpress/layouts/
|
否（URL 遵循 空间 → 页面 的层级） |
| 基于 OpenAPI 的 API 参考 | 否 | 是（内置） |
| 独立工具链 | 单一 Rust 二进制文件（npm、PyPI 或 crates.io） | 用户侧无；SaaS |
输出与部署
htmlpress 会把每个页面写成 .htmlpress/build/ 中的静态 HTML，同时生成
robots.txt、设置了 site 时的
sitemap.xml、每个页面的 Markdown 副本、llms.txt，以及
.well-known/agent-skills/ 下的智能体技能。base
键可让站点在子路径下提供服务。各托管平台的指南见部署。
GitBook 不会产出可部署的构件。站点默认托管在
<space>.gitbook.io，也可以通过 DNS
绑定自定义域名。CDN、TLS、重定向、访问控制和分析都在 GitBook
控制台中配置。自托管仅限 Enterprise 版，标准套餐不提供。最接近“你的内容”的构件，是
Git Sync 镜像写入所连接仓库的那些文件，而它们只是内容——并不是一个可构建的站点。
另请参阅
用 ❤ 和 Htmlpress 构建