Starlight 与 Htmlpress 对比
Starlight 是 Astro 官方的文档主题，由 Astro 团队维护。它采用 Astro 的孤岛架构（默认零 JavaScript，交互组件按需启用），并支持 MDX 内容。
概览
| 维度 | Htmlpress | Starlight |
|---|---|---|
| 语言 / 运行时 | Rust（单一二进制文件，无运行时） | TypeScript / Node 18+ |
| UI 框架 | 无（纯 HTML + CSS，htmlpress-* Web 组件） |
Astro 组件（HTML 优先），可选 React/Vue/Svelte/Solid 孤岛 |
| 构建工具 | htmlpress 二进制文件 | Astro（底层基于 Vite） |
| 内容格式 | HTML 和 Markdown 页面 | Markdown + MDX + MDoc |
| 许可证 | MIT，自托管 | MIT，自托管 |
| 输出模式 | 预渲染静态页面 | 预渲染静态页面（可通过适配器实现 SSR） |
架构
htmlpress 是一个 Rust 二进制文件，可从 npm（gethtmlpress）、PyPI 或
crates.io 安装。它用一个布局包裹每个 HTML 页面，并配上导航和主题；没有打包器、没有
UI 框架，也没有插件
API。每个内置文件——布局、样式、脚本以及每个组件——都可以被覆盖：在
.htmlpress/ 下的相同路径放一个文件即可替换它。
htmlpress 页面在构建时渲染为 HTML，不进行任何水合：交互式的
htmlpress-*
组件是自定义元素，各自带一个小巧的原生脚本，只会链接到使用它们的页面。
Starlight 采用 Astro 的孤岛模型：页面在构建时渲染为 HTML，默认零
JavaScript。交互组件是显式声明的“孤岛”，按需进行水合。Starlight 的默认主题主要由
Astro 组件构成（没有客户端 JS）；使用 React/Vue/Svelte 需要主动启用。Astro
的组件模型是 Astro 自有的 .astro 语法（HTML + JS
frontmatter，经静态分析）。
在 htmlpress 这边，内容布局不受约束：它按 glob 扫描（htmlpress.yaml
中的 include/exclude，默认扫描所有
.html 文件），页面的 URL 取决于它在 glob 基础目录下的文件路径，因此
docs/**/*.html 会把 docs/guide.html 发布在
/guide/。不要求存在 docs/
文件夹。导航由文件夹结构和每个页面的
<meta name="order"> 构建；文件夹的
index.html 为其分组命名。Starlight 要求内容放在
src/content/docs/（Astro
的内容集合目录）中，路由由该根目录下的文件路径推导而来。
内容层面
Starlight 接受带 frontmatter 的 Markdown + MDX，另外还支持
MDoc（Markdoc），用于带自定义标签的结构化、可校验内容。.mdx
文件中的组件默认是 Astro 组件；框架组件（React 等）需要显式的
client:* 指令才能水合。
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> 标签会原样保留。Starlight 使用
frontmatter：title、description、sidebar、tableOfContents、editUrl、lastUpdated。
功能矩阵
| 功能 | Htmlpress | Starlight |
|---|---|---|
| 版本管理 | 部分支持（每个版本一个分区或一次部署） | 否（社区插件） |
| 国际化（i18n） | 是（翻译、语言选择器、内置 7 种界面语言） | 是（内置） |
| 搜索 | 是（内置，客户端） | 是（Pagefind，内置） |
| 默认零 JS | 否（小巧的原生脚本，无框架） | 是（孤岛架构） |
| 博客 | 否 | 否（使用 Astro 的内容集合） |
| 更新日志 | 否 | 否 |
| 站点地图 | 是（需设置 site） |
是 |
| RSS | 否 | 通过 @astrojs/rss 集成 |
| 主题 | .htmlpress/ 中的覆盖文件 + --htmlpress-* 令牌 |
通过 Starlight 插槽覆盖组件 |
| 插件 | 否（使用 .htmlpress/components/ 中的项目组件） |
Astro 集成 + Starlight 插件 |
| 自定义路由 |
任意 .html 文件；额外布局放在 .htmlpress/layouts/
|
与 Starlight 内容并存的 Astro 页面 |
输出与部署
两者都会生成一个包含静态 HTML 和资源文件的目录。Starlight 默认输出到
dist/；htmlpress 输出到 .htmlpress/build/。
htmlpress 会把每个页面写成 .htmlpress/build/ 中的静态 HTML，同时生成
robots.txt、设置了 site 时的
sitemap.xml、每个页面的 Markdown 副本、llms.txt，以及
.well-known/agent-skills/ 下的智能体技能。base
键可让站点在子路径下提供服务。各托管平台的指南见部署。
Starlight 沿用 Astro 的适配器体系，支持在 Cloudflare、Netlify、Vercel、Node 和 Deno 上进行 SSR。htmlpress 没有服务端模式：构建结果只能是静态的。
另请参阅
用 ❤ 和 Htmlpress 构建