# 配置文件

> htmlpress 配置文件的位置、它控制的内容，以及顶层选项一览。

> **Info**
>
> 配置文件是可选的。默认情况下，htmlpress 会读取你指定的文件夹中的所有 `.html` 文件。

Htmlpress 通过项目根目录下的单个文件进行配置： **`htmlpress.yaml`**。把它放在页面旁边，htmlpress 就会自动读取：无需命令行参数，也无需环境变量。它的键沿用 [Livemark](https://livemark.dev) 的配置。

## 最小配置

每个键都是可选的，所以项目完全可以没有配置。最小的有用配置只是为站点命名：

```yaml
title: My docs
```

空的 `htmlpress.yaml` 等同于没有配置。没有配置时，项目下的每个 `.html` 和 `.md` 文件（默认 `include: ["**/*.html", "**/*.md"]`）都会成为页面，使用内置的布局和主题渲染：侧边栏、目录、深色模式，全部采用默认值。其他文件都会按原样复制到输出目录的相同路径下。像 `.git/` 和 `.htmlpress/` 这样的点文件夹，以及 `node_modules/`，都会被跳过。

## 可配置的内容

每个键都有合理的默认值。完整列表如下：

| 键                                 | 默认值                                    | 用途                                                                                                                                                                                                                                    |
| --------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include`                         | `**/*.html`、`**/*.md`                  | 一个 glob 或一个列表：成为页面的 `.html` 和 `.md` 文件；与同名 `.html` 并存的 `.md` 会按原样复制                                                                                                                                                                   |
| `exclude`                         | 无                                      | 一个 glob 或一个列表：完全排除在构建之外的文件，无论是否为页面                                                                                                                                                                                                    |
| `title`                           | 文件夹名                                   | 页眉以及每个浏览器标签页的标题                                                                                                                                                                                                                       |
| `description`                     | 无                                      | 用于没有自身描述的页面                                                                                                                                                                                                                           |
| `site`                            | 无                                      | 公开 URL，用于规范链接、社交链接和 `sitemap.xml`                                                                                                                                                                                                     |
| `base`                            | 无                                      | 站点所在的子路径，例如 GitHub Pages 上的 `/repo/`；参见 [基础路径](#base-path)                                                                                                                                                                            |
| `logo`                            | 无                                      | 图片的 URL，显示在站点标题之前                                                                                                                                                                                                                     |
| `favicon`                         | logo                                   | 站点图标的 URL                                                                                                                                                                                                                             |
| `banner`                          | 无                                      | 页眉上方公告栏的 HTML                                                                                                                                                                                                                         |
| `breadcrumbs`                     | `true`                                 | 在每个页面内容上方显示文件夹路径；页面的 `<meta name="breadcrumbs">` 会覆盖它                                                                                                                                                                                 |
| `head`                            | 无                                      | 添加到每个页面 head 中的 `meta`、`links` 和 `scripts`；参见 [站点元数据](/zh/customization/site-metadata/)                                                                                                                                               |
| `links`                           | 无                                      | 页眉或侧边栏中的链接；参见 [外部链接](/zh/customization/external-links/)                                                                                                                                                                               |
| `sections`                        | 无                                      | 拥有独立导航的站点部分；参见 [文章分区](/zh/customization/article-sections/)                                                                                                                                                                            |
| `edit`                            | 无                                      | "编辑此页"链接：该 URL 后接页面路径                                                                                                                                                                                                                 |
| `contentSignals`                  | 全部为 `true`                             | `search`、`aiInput` 和 `aiTrain`：自动化系统可以如何使用内容，写入 `robots.txt`；参见 [AI 智能体](/zh/customization/ai-agents/)                                                                                                                                |
| `codeThemeLight`, `codeThemeDark` | `catppuccin-latte`, `catppuccin-mocha` | 代码块主题；参见 [语法主题](/zh/customization/syntax-themes/)。                                                                                                                                                                                    |
| `patches`                         | 无                                      | 通过配置设置的页面元数据，以及作为页面发布的 `.md` 文件；参见 [文章补丁](/zh/customization/article-patches/)。                                                                                                                                                        |
| `plugins`                         | 无                                      | 加入页面流水线的 [Textlane](https://textlane.dev) 插件，每项为名称或 `{ name, options }`：`md` 作用于 Markdown 页面在指令之后的语法树，`html` 作用于每个页面在生成标题 id 之前的语法树。htmlpress 已运行的插件（如 `md.gfm` 或 `html.slug`）会用你的选项重新配置，而不会运行两次；参见 [插件](/zh/customization/plugins/)。 |
| `skills`                          | 无                                      | 一个 glob 或一个 `SKILL.md` 文件列表，路径相对于项目，作为[智能体技能](/zh/customization/ai-agents/)发布                                                                                                                                                         |
| `languages`                       | 一种，英语                                  | 站点发布的语言，默认语言在前；参见 [翻译](/zh/customization/translations/)                                                                                                                                                                               |

设置了 `languages` 后，读者看到的文本（`title`、 `description`、`banner`，以及链接和分区的标题）也可以接受按语言代码组织的映射，例如 `title: { en: Docs, es: Guía }`。

完整的 schema 位于 [`rust/src/models/config.rs`](https://github.com/datisthq/htmlpress/blob/main/rust/src/models/config.rs)。未知的键会报错，因此拼写错误绝不会被悄悄忽略。

### 包含与排除

`include` 会替换默认值，所以要列出你需要的每个文件夹。每个 glob 中第一个通配符之前的文件夹是它的基础目录：只读取基础目录下的文件，并在提供时去掉该基础目录，因此 `docs/**/*.html` 会把 `docs/guide.html` 构建为 `/guide/`。基础目录下的其他文件，包括被 `include` 排除的 `.html` 文件，都按原样复制。

glob 相对于项目，且不能离开项目（`..` 或绝对路径会报错）：`*` 只在一个文件夹内匹配， `**` 可跨越文件夹；没有匹配到任何文件的 `include` 或 `exclude` 模式会打印警告。

### 基础路径

设置 `base` 后，构建中的每个根相对 URL（位于 `href`、`src`、`srcset`、`poster` 和 `action` 中，无论在页面、布局还是配置的 HTML 中）都会加上它作为前缀：写 `/guide/`，站点就会链接到 `/repo/guide/`。相对 URL 和绝对 URL 保持不变，页面自身 CSS 中的 `url()` 也不受影响。`start` 和 `preview` 同样在基础路径下提供站点，并把 `/` 重定向到那里；修改 `base` 后需重启 `start`。

## 完整示例

大多数实际站点最终看起来都类似这样：

```yaml
site: https://htmlpress.dev
title: Htmlpress
description: Static site generator
logo: /logo.svg
banner: 'Version 1 is out: <a href="/changelog/">read more</a>'
include: docs/**/*.html
exclude: docs/**/_*
links:
  - title: GitHub
    url: https://github.com/datisthq/htmlpress
  - title: Chat
    url: https://discord.gg/example
    position: sidebar
head:
  scripts:
    - src: https://stats.example.com/script.js
      defer: ""
contentSignals:
  aiTrain: false
skills: .skills/*/SKILL.md
edit: https://github.com/datisthq/htmlpress/edit/main/docs/
```

## 下一步

- [站点元数据](/zh/customization/site-metadata/)：标题、描述、favicon、logo。
- [文章分区](/zh/customization/article-sections/)：将站点划分为拥有独立导航的分区。
- [外部链接](/zh/customization/external-links/)：页眉和侧边栏链接。
- [语法主题](/zh/customization/syntax-themes/)：代码块的外观。
- [文章补丁](/zh/customization/article-patches/)：通过配置覆盖页面元数据。
- [覆盖/弹出](/zh/customization/overriding-escaping/)：替换任何内置的布局、样式表或组件。
- [自定义路由](/zh/customization/custom-routes/)：拥有独立布局的页面。