Htmlpress

Htmlpress 是为人类与智能体打造的静态站点生成器。它把一个装满 Markdown 和 HTML 页面的文件夹变成一个站点。每个页面保留自己的标记，htmlpress 则添加一个布局、一套主题、一个导航和一个支持实时重载的开发服务器。它是一个 Rust 二进制文件，可通过 npm、PyPI 或 crates.io 安装。

你或你的智能体编写纯 Markdown 或语义化 HTML——智能体对它们的了解远胜于任何模板语言——而每个页面最终看起来都属于同一个站点：没有框架，没有构建配置，没有工具类。

你将获得

• 只需编写 Markdown 或 HTML。页面可以是带 frontmatter 的任意 .md 文件，也可以是任意 .html 文件（完整文档或裸片段），其 <title> 和 <meta> 标签承担 frontmatter 的作用；参见 Markdown 页面。
• 基于元素的主题样式。标题、表格、代码块、<details>、<figure> 等元素无需任何类名即可正确呈现，并支持浅色和深色模式。
• 丰富的元素。提示框、标签页、步骤、卡片、徽章、文件树、可排序表格、终端、包管理器标签页（npm/pnpm/yarn/bun）、Mermaid 图表和嵌入内容（YouTube、SoundCloud），全部以 htmlpress-* 自定义元素的形式提供。
• 开箱即用的导航。按文件夹嵌套的侧边栏、面包屑导航、目录、上一页/下一页链接，以及“编辑此页”链接。
• 多语言。译文与原文并列存放，提供语言选择器，界面内置七种语言；参见翻译。
• 为智能体打造。每次构建都会为每个页面发布一份 Markdown 副本、llms.txt 以及你的智能体技能；每条命令都支持 JSON。
• 可定制主题。提供 --htmlpress-* 令牌，并可通过 .htmlpress/ 文件夹逐个文件覆盖布局、样式和组件。
• 单一二进制文件。无运行时、无依赖：生成带有 sitemap.xml、robots.txt 和 404 页面的静态站点，可部署到任何托管平台。

快速开始

你只需要这个二进制文件。每个渠道都以相同版本发布同一个二进制文件，所以选择项目已经在用的包管理器即可。

安装

curl -fsSL https://htmlpress.dev/install.sh | sh

npm install --global gethtmlpress
# or run it without installing
npx gethtmlpress --version

pip install htmlpress
# or run it without installing
uvx htmlpress --version

cargo install htmlpress

预构建的二进制文件覆盖 x64 和 arm64 架构上的 Linux、macOS 和 Windows：

在其他平台上，请使用 cargo install htmlpress 构建；如果使用 npm 包，再将 HTMLPRESS_BINARY 指向构建结果。

配置

配置是可选的。要设置站点的元数据，请在项目根目录创建 htmlpress.yaml：

title: My docs
description: Documentation for my project
include: docs/**/*.html

没有 include 时，项目中的每个 .html 文件都是一个页面；设置后，只有匹配的文件才是页面，并且去掉 glob 的基础路径后提供服务，因此 docs/usage.html 位于 /usage/。所有键请参见配置文件。

添加内容

每个页面通过片段中也可以携带的标签来设置标题、描述和顺序：

<title>Getting Started</title>
<meta name="description" content="Set up the project in five minutes." />
<meta name="order" content="1" />

<h1>Getting Started</h1>
<p>Welcome!</p>

---
title: Getting Started
description: Set up the project in five minutes.
order: 1
---

# Getting Started

Welcome!

各标签的含义请参见 Frontmatter。

运行

htmlpress start    # dev server with live reload at http://localhost:8000
htmlpress build    # production build to .htmlpress/build/
htmlpress preview  # serve the production build locally
htmlpress clear    # remove .htmlpress/build/

整个流程就是这样。把 .htmlpress/build/ 加入你的 .gitignore。本站正是用这种方式，从仓库的 rust/docs/ 文件夹构建而成。

项目结构

一个典型的 htmlpress 站点：

位于 .htmlpress/ 下、路径与内置文件相同的文件，例如 layout.html、styles/tokens.css 或 components/tabs/tabs.css，会替换默认文件，因此无需 fork 即可自定义布局、主题和组件。运行 htmlpress escape <name> 可将默认文件复制到 .htmlpress/ 中以便编辑。

命令

htmlpress build [root]

将位于 root（默认为 .）的项目渲染到 root/.htmlpress/build，并替换其中已有的内容。--out / -o 可指定其他文件夹；如果该文件夹会包含项目本身，或是项目内的可见文件夹，则会被拒绝，因为其中的页面会被当作源文件重新读取。

$ htmlpress build docs
built 6 pages and 0 files into docs/.htmlpress/build

htmlpress start [root]

构建项目，在 http://localhost:8000 上提供服务，并在每次更改时重新构建。已打开的页面会在每次构建后自动重载。构建失败时会打印错误并在浏览器中显示：覆盖在已打开的页面上，并替代之后打开的任何页面。即使第一次构建失败，服务器也会继续运行，下一次成功的构建会重载所有页面。

当 8000 端口被占用时，它会依次尝试 8001 直到 8009，并打印实际获得的 URL。 --port / -p 可指定一个端口（0 表示任选一个空闲端口）。单独使用 --host 会在所有地址上提供服务，这样同一网络中的手机也能打开站点，同时也会打印该 URL； --host <address> 则只在一个地址上提供服务。如果在 htmlpress.yaml 中设置了 base，站点会在该路径下提供服务，打印的 URL 会包含它，/ 会跳转到那里；修改 base 后需要重启。--open 会在服务启动后用浏览器打开站点；--open <path> 则打开 base 下的该页面。 --out / -o 的作用与 build 相同。

$ htmlpress start docs --host
serving http://localhost:8000
network http://192.168.1.107:8000

htmlpress preview [root]

以生产模式构建项目，并按部署后的样子提供服务：不监听文件，也不重载。与 start 一样接受 --port、--host、--open 和 --out。

htmlpress clear [root]

删除构建输出（用 --out 指定其他目录），与 build 具有相同的保护机制。

htmlpress escape [names…]

将内置文件复制到 .htmlpress/ 中以便编辑：名称可以是路径，例如 components/tabs/tabs.js，也可以是组件的标签，表示其全部文件。不带名称时，它会列出所有内置文件，以及项目是否已弹出它们。--root / -r 指定项目（默认为 .）。它不会覆盖已有文件；参见覆盖/弹出。

$ htmlpress escape htmlpress-tabs
escaped .htmlpress/components/tabs/tabs.css
escaped .htmlpress/components/tabs/tabs.js

面向脚本和智能体

该 CLI 基于 Fireargs 构建，因此每条命令都支持 JSON。--json 会以 JSON 格式输出结果；如果带上一个值，它还会以 JSON 格式接收输入：

$ htmlpress build docs --json
{
  "output": "docs/.htmlpress/build",
  "pages": 6,
  "files": 0
}
$ htmlpress build --json '{"root":"docs","out":"dist"}'

htmlpress start --json 和 preview --json 不会结束，因此服务器开始监听时会以一行打印 {"url": "…", "network": []}。

htmlpress --llms 会以 MCP 风格的工具列表打印每条命令的输入和输出模式，这样智能体无需阅读本页就能学会使用该 CLI。

自定义

Htmlpress 的目标是零配置即可呈现良好效果，并在你需要更多功能时不碍事。常见的自定义：

• 站点元数据：标题、描述、favicon、Logo。参见站点元数据。
• 分区：在侧边栏中按文件夹对页面分组。参见文章分区。
• 外部链接：在页眉和侧边栏中添加指向任意位置的链接。参见外部链接。
• 覆盖/弹出：在项目中替换布局、任意样式表或组件。参见覆盖/弹出。
• AI 智能体：每次构建为智能体发布的内容。参见AI 智能体。

文档

完整文档位于 htmlpress.dev：

• 编写参考：所有元素和组件及其示例
• 自定义：所有可调选项，附可直接复制的代码片段
• 部署：将构建结果发布到托管平台
• 贡献：本地环境搭建和 PR 流程

资源

• npm： npmjs.com/package/gethtmlpress
• PyPI： pypi.org/project/htmlpress
• crates.io： crates.io/crates/htmlpress
• GitHub： github.com/datisthq/htmlpress
• 问题反馈： github.com/datisthq/htmlpress/issues
• 讨论区： github.com/datisthq/htmlpress/discussions

许可证

MIT；参见 LICENSE.md。