MkDocs 与 Htmlpress 对比

MkDocs 是一个基于 Python 的文档生成器。内容是纯 Markdown，布局是 Jinja2 模板，主题是可通过 pip 安装的 Python 包。事实上的标准主题是 Material for MkDocs，大多数用户实际使用的就是它。

概览

架构

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 定义导航。

功能矩阵

输出与部署

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

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

另请参阅

• 编写——htmlpress 的 HTML 编写方式。
• 自定义——htmlpress 的配置键与覆盖文件。
• 对比——返回索引。