# 简介 > 了解如何搭建你的第一个 htmlpress 项目：安装、编写页面、运行和构建。 Htmlpress 是为人类与智能体打造的静态站点生成器。它把一个装满 Markdown 和 HTML 页面的文件夹变成一个站点。每个页面保留自己的标记，htmlpress 则添加一个布局、一套主题、一个导航和一个支持实时重载的开发服务器。它是一个 Rust 二进制文件，可通过 npm、PyPI 或 crates.io 安装。 你或你的智能体编写纯 Markdown 或语义化 HTML——智能体对它们的了解远胜于任何模板语言——而每个页面最终看起来都属于同一个站点：没有框架，没有构建配置，没有工具类。 > **Warning** > > Htmlpress 目前处于技术预览阶段：在 1.0 之前，页面约定仍可能发生变化。 ## 你将获得 - **只需编写 Markdown 或 HTML。**页面可以是带 frontmatter 的任意 `.md` 文件，也可以是任意 `.html` 文件（完整文档或裸片段），其 `` 和 `<meta>` 标签承担 frontmatter 的作用；参见 [Markdown 页面](/zh/authoring/markdown-pages/)。 - **基于元素的主题样式。**标题、表格、代码块、`<details>`、`<figure>` 等元素无需任何类名即可正确呈现，并支持浅色和深色模式。 - **丰富的元素。**提示框、标签页、步骤、卡片、徽章、文件树、可排序表格、终端、包管理器标签页（npm/pnpm/yarn/bun）、Mermaid 图表和嵌入内容（YouTube、SoundCloud），全部以 `htmlpress-*` 自定义元素的形式提供。 - **开箱即用的导航。**按文件夹嵌套的侧边栏、面包屑导航、目录、上一页/下一页链接，以及“编辑此页”链接。 - **多语言。**译文与原文并列存放，提供语言选择器，界面内置七种语言；参见[翻译](/zh/customization/translations/)。 - **为智能体打造。**每次构建都会为每个页面发布一份 Markdown 副本、`llms.txt` 以及你的智能体技能；每条命令都支持 JSON。 - **可定制主题。**提供 `--htmlpress-*` 令牌，并可通过 `.htmlpress/` 文件夹逐个文件覆盖布局、样式和组件。 - **单一二进制文件。**无运行时、无依赖：生成带有 `sitemap.xml`、`robots.txt` 和 404 页面的静态站点，可部署到任何托管平台。 ## 快速开始 你只需要这个二进制文件。每个渠道都以相同版本发布同一个二进制文件，所以选择项目已经在用的包管理器即可。 ### 安装 **Script** ```sh curl -fsSL https://htmlpress.dev/install.sh | sh ``` 从 [GitHub releases](https://github.com/datisthq/htmlpress/releases) 下载适用于你所在平台的二进制文件，校验其 SHA-256 后放入 `~/.local/bin`。设置 `HTMLPRESS_VERSION` 可固定版本，设置 `HTMLPRESS_INSTALL_DIR` 可安装到其他目录。 **npm** ``` npm install --global gethtmlpress # or run it without installing npx gethtmlpress --version ``` `gethtmlpress` 包通过可选依赖引入一个平台包，例如 `@htmlpress/linux-x64`。使用 `--omit=optional` 安装会遗漏二进制文件。 **PyPI** ```sh pip install htmlpress # or run it without installing uvx htmlpress --version ``` 对应你所在平台的 wheel 携带了二进制文件；不会运行任何 Python 代码。 **Cargo** ```sh cargo install htmlpress ``` 使用 1.88 或更高版本的 Rust 工具链从源码构建。 预构建的二进制文件覆盖 x64 和 arm64 架构上的 Linux、macOS 和 Windows： | 平台 | npm 包 | Rust 目标 | | ------------- | ------------------------- | ---------------------------- | | Linux x64 | `@htmlpress/linux-x64` | `x86_64-unknown-linux-musl` | | Linux arm64 | `@htmlpress/linux-arm64` | `aarch64-unknown-linux-musl` | | macOS x64 | `@htmlpress/darwin-x64` | `x86_64-apple-darwin` | | macOS arm64 | `@htmlpress/darwin-arm64` | `aarch64-apple-darwin` | | Windows x64 | `@htmlpress/win32-x64` | `x86_64-pc-windows-msvc` | | Windows arm64 | `@htmlpress/win32-arm64` | `aarch64-pc-windows-msvc` | 在其他平台上，请使用 `cargo install htmlpress` 构建；如果使用 npm 包，再将 `HTMLPRESS_BINARY` 指向构建结果。 ### 配置 配置是可选的。要设置站点的元数据，请在项目根目录创建 `htmlpress.yaml`： ```yaml title: My docs description: Documentation for my project include: docs/**/*.html ``` 没有 `include` 时，项目中的每个 `.html` 文件都是一个页面；设置后，只有匹配的文件才是页面，并且去掉 glob 的基础路径后提供服务，因此 `docs/usage.html` 位于 `/usage/`。所有键请参见[配置文件](/zh/customization/configuration-file/)。 ### 添加内容 - docs/ - index.html - getting-started.html - usage.html 每个页面通过片段中也可以携带的标签来设置标题、描述和顺序： **HTML** ```html <title>Getting Started

Getting Started

Welcome!

``` **Markdown** ```md --- title: Getting Started description: Set up the project in five minutes. order: 1 --- # Getting Started Welcome! ``` 各标签的含义请参见 [Frontmatter](/zh/authoring/frontmatter/)。 ### 运行 ```sh 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/](https://github.com/datisthq/htmlpress/tree/main/rust/docs) 文件夹构建而成。 ## 项目结构 一个典型的 htmlpress 站点： - my-project/ - htmlpress.yaml — 配置（可选） - index.html — 首页 - guides/ — 一个侧边栏分组，以其 `index.html` 命名 - index.html - build.html - logo.svg — 其他任意文件，原样复制 - .htmlpress/ — 弹出文件和构建输出 - layout.html - build/ 位于 `.htmlpress/` 下、路径与内置文件相同的文件，例如 `layout.html`、`styles/tokens.css` 或 `components/tabs/tabs.css`，会替换默认文件，因此无需 fork 即可自定义布局、主题和组件。运行 `htmlpress escape ` 可将默认文件复制到 `.htmlpress/` 中以便编辑。 ## 命令 ### `htmlpress build [root]` 将位于 `root`（默认为 `.`）的项目渲染到 `root/.htmlpress/build`，并替换其中已有的内容。`--out` / `-o` 可指定其他文件夹；如果该文件夹会包含项目本身，或是项目内的可见文件夹，则会被拒绝，因为其中的页面会被当作源文件重新读取。 ```sh $ 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
` 则只在一个地址上提供服务。如果在 `htmlpress.yaml` 中设置了 `base`，站点会在该路径下提供服务，打印的 URL 会包含它，`/` 会跳转到那里；修改 `base` 后需要重启。`--open` 会在服务启动后用浏览器打开站点；`--open ` 则打开 `base` 下的该页面。 `--out` / `-o` 的作用与 `build` 相同。 ```sh $ 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` 指定项目（默认为 `.`）。它不会覆盖已有文件；参见[覆盖/弹出](/zh/customization/overriding-escaping/)。 ```sh $ htmlpress escape htmlpress-tabs escaped .htmlpress/components/tabs/tabs.css escaped .htmlpress/components/tabs/tabs.js ``` ### 面向脚本和智能体 该 CLI 基于 [Fireargs](https://fireargs.dev) 构建，因此每条命令都支持 JSON。`--json` 会以 JSON 格式输出结果；如果带上一个值，它还会以 JSON 格式接收输入： ```sh $ 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。参见[站点元数据](/zh/customization/site-metadata/)。 - **分区**：在侧边栏中按文件夹对页面分组。参见[文章分区](/zh/customization/article-sections/)。 - **外部链接**：在页眉和侧边栏中添加指向任意位置的链接。参见[外部链接](/zh/customization/external-links/)。 - **覆盖/弹出**：在项目中替换布局、任意样式表或组件。参见[覆盖/弹出](/zh/customization/overriding-escaping/)。 - **AI 智能体**：每次构建为智能体发布的内容。参见[AI 智能体](/zh/customization/ai-agents/)。 ## 文档 完整文档位于 **[htmlpress.dev](https://htmlpress.dev)**： - [编写参考](/zh/authoring/)：所有元素和组件及其示例 - [自定义](/zh/customization/)：所有可调选项，附可直接复制的代码片段 - [部署](/zh/deployment/)：将构建结果发布到托管平台 - [贡献](/zh/contributing/)：本地环境搭建和 PR 流程 ## 资源 - **npm**： [npmjs.com/package/gethtmlpress](https://www.npmjs.com/package/gethtmlpress) - **PyPI**： [pypi.org/project/htmlpress](https://pypi.org/project/htmlpress/) - **crates.io**： [crates.io/crates/htmlpress](https://crates.io/crates/htmlpress) - **GitHub**： [github.com/datisthq/htmlpress](https://github.com/datisthq/htmlpress) - **问题反馈**： [github.com/datisthq/htmlpress/issues](https://github.com/datisthq/htmlpress/issues) - **讨论区**： [github.com/datisthq/htmlpress/discussions](https://github.com/datisthq/htmlpress/discussions) ## 许可证 MIT；参见 [LICENSE.md](https://github.com/datisthq/htmlpress/blob/main/LICENSE.md)。