# Docsify vs Htmlpress

> 静态站点构建器与浏览器中的运行时 Markdown 渲染器之比。

[Docsify](https://docsify.js.org) 是一款文档站点工具，它的做法与本节其他所有工具都不同：它不在构建时生成静态 HTML，而是只提供一个 `index.html` 加上一个 JavaScript 运行时，在浏览器中获取 Markdown 文件并即时渲染。没有构建步骤。

## 概览

| 维度       | Htmlpress                            | Docsify                          |
| -------- | ------------------------------------ | -------------------------------- |
| 语言 / 运行时 | Rust（单一二进制，无运行时）                     | 浏览器 JavaScript（无构建）              |
| UI 框架    | 无（纯 HTML + CSS，`htmlpress-*` Web 组件） | 原生 JS + Vue 风格的模板指令              |
| 构建工具     | htmlpress 二进制文件                      | 无（运行时获取 + 渲染）                    |
| 内容格式     | HTML 和 Markdown 页面                   | Markdown（在浏览器中使用 marked / Prism） |
| 许可证      | MIT，自托管                              | MIT，自托管                          |
| 输出模型     | 预渲染静态                                | 从原始 `.md` 文件进行客户端渲染              |

## 架构

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

Docsify 没有构建流水线。一个站点就是一个 `index.html`，它从 CDN（或 `node_modules`）加载 `docsify.js`，并在 `window.$docsify` 上配置一个小型配置对象。运行时，脚本读取 URL 哈希（`#/some/page`），用 `fetch()` 获取对应的 `.md` 文件，交给 `marked` 解析 Markdown、`Prism` 做语法高亮，然后把结果注入页面。导航默认基于哈希；History API 模式需要手动开启，但要求服务器配置重写。

在 htmlpress 一侧，内容布局不受约束：它按 glob 扫描（`htmlpress.yaml` 中的 `include`/`exclude`，默认是所有 `.html` 文件），页面的 URL 跟随其在 glob 基础路径之下的文件路径，因此 `docs/**/*.html` 会把 `docs/guide.html` 提供在 `/guide/`。不要求存在 `docs/` 文件夹。导航由文件夹和每个页面的 `<meta name="order">` 构建；文件夹的 `index.html` 为其分组命名。Docsify 从单一源根目录读取（包含 `index.html` 的目录，可通过 `basePath` 配置），请求 URL 直接映射到磁盘上的文件路径——`#/guide/install` 会获取 `guide/install.md`。侧边栏导航需要在 `_sidebar.md` 中手动编写；没有自动生成的导航。

## 内容形式

Docsify 支持纯 Markdown（通过 `marked` 实现 CommonMark）以及少量内置扩展：辅助语法（通过 [docsify-tabs](https://jhildenbiddle.github.io/docsify-tabs/) 和 admonition 插件实现的 `> [!TIP]` 风格提示框）、HTML 直通，以及在加载可选 Vue 编译器时有限的 Vue 模板风格指令。没有 MDX，默认不解析 frontmatter（可由插件添加），也没有按页面的 React 组件。插件通过把函数推入 `window.$docsify.plugins` 来注册，并挂接到生命周期（`init`、`mounted`、 `beforeEach`、`afterEach`、`doneEach`、 `ready`）。

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>` 标签会被保留。

## 功能矩阵

| 能力        | Htmlpress                                  | Docsify                           |
| --------- | ------------------------------------------ | --------------------------------- |
| 版本管理      | 部分支持（每个版本一个分区或一次部署）                        | 是（通过 `alias` 配置实现多实例）             |
| 国际化（i18n） | 是（翻译、语言选择器、内置 7 种界面语言）                     | 是（`fallbackLanguages` + 按语言区域的文件） |
| 搜索        | 是（内置，客户端）                                  | 是（内置全文搜索插件）                       |
| 博客        | 否                                          | 否                                 |
| 更新日志      | 否                                          | 否（手动）                             |
| Sitemap   | 是（设置 `site` 时）                             | 否（第三方插件）                          |
| RSS       | 否                                          | 否                                 |
| 主题        | `.htmlpress/` 中的弹出文件 + `--htmlpress-*` 令牌  | CSS 主题（`vue.css`、`buble.css` 等）   |
| 插件        | 否（`.htmlpress/components/` 中的项目组件）         | `window.$docsify` 上的运行时 JS 插件     |
| 自定义路由     | 任意 `.html` 文件；`.htmlpress/layouts/` 中的额外布局 | 否（URL 与文件路径一一对应）                  |
| 独立工具链     | 单一 Rust 二进制（npm、PyPI 或 crates.io）          | 运行时无；`docsify-cli` 仅用于初始化         |

## 输出与部署

这是两者分歧最大的地方。

htmlpress 生成一个由预渲染 HTML + 资源组成的目录（`.htmlpress/build/`）。每个页面都是真实的 HTML 文件；爬虫、链接预览和禁用 JS 的客户端都能看到渲染后的内容。htmlpress 把每个页面写为 `.htmlpress/build/` 中的静态 HTML，同时写出 `robots.txt`、设置了 `site` 时的 `sitemap.xml`、每个页面的 Markdown 副本、`llms.txt`，以及位于 `.well-known/agent-skills/` 下的智能体技能。`base` 键让站点在子路径下提供服务。托管平台指南见 [部署](/zh/deployment/)。

Docsify 把原始 `.md` 文件与 `index.html` 一起发布。所谓“部署”就是把源目录上传到任意静态托管平台。代价是：零构建时间、编辑即刷新的写作体验，换来的是首次绘制时 HTML 为空——搜索引擎、社交预览和无 JS 客户端只能看到加载器外壳。该项目文档介绍了一种使用 `docsify-ssr` 或外部预渲染器的 [SSR/预渲染工作流](https://docsify.js.org/#/ssr)，用于为 SEO 敏感的站点缓解这一问题。

## 另请参阅

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