VitePress 与 Htmlpress 对比

VitePress 是 Vue 官方的文档框架，基于 Vite 构建。它以 Markdown 为先，自带一个极简的默认主题，大多数 Vue 生态的文档（Vue 本身、Vite、Pinia 等）都由它驱动。

概览

架构

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

VitePress 用自己的 SSG 流水线封装 Vite，并渲染 Vue。它的运行时是 vue-router 加上一个内置的默认主题。

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

内容层面

VitePress 接受内置 Vue 模板支持的 Markdown——你可以在 .md 文件中使用 Vue 组件和 <script setup> 块。它不支持 React 意义上的 MDX。

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> 标签会原样保留。VitePress 使用 frontmatter：title、layout、sidebar、outline、prev/next。

标注/提示框：VitePress 使用 ::: tip / ::: warning 容器；htmlpress 使用 <htmlpress-callout type="warning">。

功能矩阵

输出与部署

两者都会生成一个包含静态 HTML 和资源文件的目录，可部署到任意静态托管平台。VitePress 默认输出到 .vitepress/dist/；htmlpress 输出到 .htmlpress/build/。

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

另请参阅

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