# MkDocs 与 Htmlpress 对比

> Rust + 纯 HTML 与 Python + Jinja2 + Markdown。

[MkDocs](https://www.mkdocs.org) 是一个基于 Python 的文档生成器。内容是纯 Markdown，布局是 Jinja2 模板，主题是可通过 pip 安装的 Python 包。事实上的标准主题是 [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)，大多数用户实际使用的就是它。

## 概览

| 维度       | Htmlpress                            | MkDocs                                    |
| -------- | ------------------------------------ | ----------------------------------------- |
| 语言 / 运行时 | Rust（单一二进制文件，无运行时）                   | Python 3.8+                               |
| UI 框架    | 无（纯 HTML + CSS，`htmlpress-*` Web 组件） | Jinja2 模板（HTML + CSS）                     |
| 构建工具     | htmlpress 二进制文件                      | MkDocs CLI                                |
| 内容格式     | HTML 和 Markdown 页面                   | Markdown（CommonMark + Python-Markdown 扩展） |
| 许可证      | MIT，自托管                              | BSD-2-Clause，自托管                          |
| 输出模式     | 预渲染静态页面                              | 预渲染静态页面                                   |

## 架构

htmlpress 是一个 Rust 二进制文件，可从 npm（`gethtmlpress`）、PyPI 或 crates.io 安装。它用一个布局包裹每个 HTML 页面，并配上导航和主题；没有打包器、没有 UI 框架，也没有插件 API。每个内置文件——布局、样式、脚本以及每个组件——都可以被覆盖：在 `.htmlpress/` 下的相同路径放一个文件即可替换它。在 PyPI 上它以二进制 wheel 发布，因此 `pip install htmlpress` 在运行时不需要任何 Python 代码。

MkDocs 是一个 Python CLI。站点通过 `mkdocs.yml` 配置。主题可通过 pip 安装；构建流水线让 Markdown 内容依次经过 Python-Markdown（或 pymdown-extensions）和 Jinja2 模板处理。没有 JavaScript 构建步骤——渲染后站点的交互性完全取决于主题模板输出的内容。

Material for MkDocs 增加了一套精心设计的主题、基于 lunr.js 的搜索索引、即时导航，以及丰富的插件生态（`mkdocs-material` 的扩展功能，加上 PyPI 上更广泛的 `mkdocs-*` 插件命名空间）。

在 htmlpress 这边，内容布局不受约束：它按 glob 扫描（`htmlpress.yaml` 中的 `include`/`exclude`，默认扫描所有 `.html` 文件），页面的 URL 取决于它在 glob 基础目录下的文件路径，因此 `docs/**/*.html` 会把 `docs/guide.html` 发布在 `/guide/`。不要求存在 `docs/` 文件夹。导航由文件夹结构和每个页面的 `<meta name="order">` 构建；文件夹的 `index.html` 为其分组命名。MkDocs 从 `docs/` 读取（可通过 `mkdocs.yml` 中的 `docs_dir` 配置），路由由该目录下的文件路径推导而来。

## 内容层面

MkDocs 接受带 frontmatter 的 Markdown；htmlpress 同样接受 HTML 页面和带 frontmatter 的 Markdown。MkDocs 通过 Python-Markdown 扩展（提示框、标签页、脚注、定义列表）和 `pymdown-extensions`（它带来完整的 Material 语法：`=== "Tab 1"` 标签页、`:::note` 提示框、`++ctrl++` 键盘快捷键等）来扩展 Markdown。若要超出这些扩展所提供的定制能力，就需要编写 Python 插件或覆盖 Jinja 模板。

htmlpress 页面是纯语义化 HTML，主题直接根据元素本身设置样式。更丰富的区块是 `htmlpress-*` 自定义元素（`htmlpress-callout`、`htmlpress-tabs`、`htmlpress-filetree`、`htmlpress-cards` 等），其 CSS 和 JS 只会链接到使用该标签的页面。项目可以通过 `.htmlpress/components/<name>/<name>.html` 添加自己的标签，它会在构建时替换该标签。同样的区块在这里就是纯 HTML 元素：`<dl>`、`<kbd>`、`<details>`。

htmlpress 没有 frontmatter：页面的元数据就是它自己的 `<head>`——`<title>`、`<meta name="description">`、`<meta name="order">`、`<meta name="layout">` 和 `<meta name="image">`；其他 `<head>` 标签会原样保留。MkDocs 读取 `title`、`summary`、`tags`（需插件）、`template`，并使用 `mkdocs.yml` 定义导航。

## 功能矩阵

| 功能        | Htmlpress                                  | MkDocs                        |
| --------- | ------------------------------------------ | ----------------------------- |
| 版本管理      | 部分支持（每个版本一个分区或一次部署）                        | 是（通过 `mike` 插件）               |
| 国际化（i18n） | 是（翻译、语言选择器、内置 7 种界面语言）                     | 是（Material 的 i18n 插件）         |
| 搜索        | 是（内置，客户端）                                  | 是（内置，客户端）                     |
| 博客        | 否                                          | 是（Material 的博客插件）             |
| 更新日志      | 否                                          | 否（手动）                         |
| 站点地图      | 是（需设置 `site`）                              | 是                             |
| RSS       | 否                                          | 通过插件                          |
| 主题        | `.htmlpress/` 中的覆盖文件 + `--htmlpress-*` 令牌  | 主题包 + Jinja 覆盖                |
| 插件        | 否（使用 `.htmlpress/components/` 中的项目组件）      | Python 插件（PyPI 上的 `mkdocs-*`） |
| 自定义路由     | 任意 `.html` 文件；额外布局放在 `.htmlpress/layouts/` | 否（仅限内容）                       |
| 独立工具链     | 单一 Rust 二进制文件（npm、PyPI 或 crates.io）        | Python + pip                  |

## 输出与部署

两款工具都会生成可部署到任意静态托管平台的静态 HTML 和资源文件。MkDocs 默认输出到 `site/`；htmlpress 输出到 `.htmlpress/build/`。

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

## 另请参阅

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