Nextra 与 Htmlpress 对比

Nextra 是一个采用主题包架构的 Next.js 文档框架。它最初基于 Pages Router，后来也迁移到支持 App Router。文档站点选择一个主题（文档用 nextra-theme-docs，博客用 nextra-theme-blog）并对其进行配置。

概览

架构

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

Nextra 是构建在现有 Next.js 应用之上的一层。搭建过程包括安装 nextra 和一个主题包，把它们接入 next.config.js，并在每个目录中通过 _meta.json（Pages Router）或 meta.js（App Router）文件定义导航。主题包掌控整个 UI；定制通过主题文档中给出的钩子完成。

nextra-theme-docs 是 Vercel、SWR、Turbo 等众多项目使用的文档主题。它稳定、持续维护，并且在文档场景下功能完备。

在 htmlpress 这边，内容布局不受约束：它按 glob 扫描（htmlpress.yaml 中的 include/exclude，默认扫描所有 .html 文件），页面的 URL 取决于它在 glob 基础目录下的文件路径，因此 docs/**/*.html 会把 docs/guide.html 发布在 /guide/。不要求存在 docs/ 文件夹。导航由文件夹结构和每个页面的 <meta name="order"> 构建；文件夹的 index.html 为其分组命名。Nextra 从 pages/（Pages Router）或 content/（App Router）读取内容，路由由文件路径和与之并列的 _meta.json 文件决定。

内容层面

Nextra 接受带 frontmatter 和内嵌 React 组件的 Markdown + MDX。它通过 next-mdx-remote 支持远程 MDX，通过插件支持 KaTeX/Mermaid，并通过 Next 的 <Image> 组件进行图片优化。

htmlpress 页面是纯语义化 HTML，主题直接根据元素本身设置样式。更丰富的区块是 htmlpress-* 自定义元素（htmlpress-callout、htmlpress-tabs、htmlpress-filetree、htmlpress-cards 等），其 CSS 和 JS 只会链接到使用该标签的页面。项目可以通过 .htmlpress/components/<name>/<name>.html 添加自己的标签，它会在构建时替换该标签。Mermaid 图表内置提供，写成 language-mermaid 代码块即可。

htmlpress 没有 frontmatter：页面的元数据就是它自己的 <head>——<title>、<meta name="description">、<meta name="order">、<meta name="layout"> 和 <meta name="image">；其他 <head> 标签会原样保留。Nextra 使用 frontmatter（title、description、searchable、hide_title），并用每个目录中的 _meta.json 定义导航；htmlpress 没有导航文件。

功能矩阵

输出与部署

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

Nextra 沿用 Next.js 的输出模式。最常见的文档配置是完全静态导出（output: 'export'），它会生成一个可部署到任何地方的静态目录。SSR 配置则以 Vercel 或 Node 托管平台为目标。

另请参阅

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