Docusaurus vs Htmlpress

Docusaurus 是由 Meta 维护的开源文档框架。它通过基于 Webpack 的构建流水线渲染 React + MDX 内容，提供一流的版本管理和国际化支持，并拥有庞大的插件生态。

概览

架构

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

Docusaurus 基于 Webpack 构建。其运行时由 React Router 加上负责主题、插件和内容源的 Docusaurus 核心组成。插件是一等公民——每个内置功能（文档、博客、页面、搜索）本身都是插件，第三方也以同样的方式扩展系统。

在 htmlpress 一侧，内容布局不受约束：它按 glob 扫描（htmlpress.yaml 中的 include/exclude，默认是所有 .html 文件），页面的 URL 跟随其在 glob 基础路径之下的文件路径，因此 docs/**/*.html 会把 docs/guide.html 提供在 /guide/。不要求存在 docs/ 文件夹。导航由文件夹和每个页面的 <meta name="order"> 构建；文件夹的 index.html 为其分组命名。Docusaurus 的 docs 插件需要一个 docs/ 目录（可通过 path 配置，但基于文件夹而非 glob）。

内容形式

Docusaurus 接受带 frontmatter 的 Markdown 和 MDX，并允许在 .md/.mdx 文件中嵌入 React 组件。htmlpress 接受 .html 页面（完整文档或裸片段）和带 frontmatter 的 .md 页面，其 :::name 指令就是它的组件；不支持 MDX，也没有 React。

htmlpress 页面是纯语义化 HTML，主题直接根据元素本身设置样式。更丰富的区块是 htmlpress-* 自定义元素（htmlpress-callout、htmlpress-tabs、 htmlpress-filetree、htmlpress-cards……），其 CSS 和 JS 只在使用该标签的页面上链接。项目可以通过 .htmlpress/components/<name>/<name>.html 添加自己的标签，它会在构建时替换该标签。Docusaurus 使用 MDX 组件以及 admonition 扩展来实现提示框。

htmlpress 没有 frontmatter：页面的元数据就是它自己的 <head>——<title>、 <meta name="description">、 <meta name="order">、<meta name="layout"> 和 <meta name="image">；其他 <head> 标签会被保留。Docusaurus 使用 id、slug、 sidebar_position、sidebar_label、tags。

功能矩阵

输出与部署

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

Docusaurus 同样预渲染为静态 HTML，输出到 build/。其静态输出可以运行在同样的托管平台上（GitHub Pages、Cloudflare、Vercel、Netlify、静态托管）。Docusaurus 的内置 i18n 会为每个语言区域生成独立的输出树。

另请参阅

• 编写——htmlpress 的 HTML 写作面。
• 自定义——htmlpress 的配置键与弹出文件。
• 对比——返回索引。