配置文件
配置文件是可选的。默认情况下，htmlpress 会读取你指定的文件夹中的所有
.html 文件。
Htmlpress 通过项目根目录下的单个文件进行配置：
htmlpress.yaml。把它放在页面旁边，htmlpress
就会自动读取：无需命令行参数，也无需环境变量。它的键沿用
Livemark 的配置。
最小配置
每个键都是可选的，所以项目完全可以没有配置。最小的有用配置只是为站点命名：
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/；参见
基础路径
|
logo |
无 | 图片的 URL，显示在站点标题之前 |
favicon |
logo | 站点图标的 URL |
banner |
无 | 页眉上方公告栏的 HTML |
breadcrumbs |
true |
在每个页面内容上方显示文件夹路径；页面的
<meta name="breadcrumbs"> 会覆盖它
|
head |
无 |
添加到每个页面 head 中的 meta、links 和
scripts；参见
站点元数据
|
links |
无 | 页眉或侧边栏中的链接；参见 外部链接 |
sections |
无 | 拥有独立导航的站点部分；参见 文章分区 |
edit |
无 | "编辑此页"链接：该 URL 后接页面路径 |
contentSignals |
全部为 true |
search、aiInput 和
aiTrain：自动化系统可以如何使用内容，写入
robots.txt；参见
AI 智能体
|
codeThemeLight, codeThemeDark |
catppuccin-latte, catppuccin-mocha |
代码块主题；参见 语法主题。 |
patches |
无 |
通过配置设置的页面元数据，以及作为页面发布的 .md 文件；参见
文章补丁。
|
plugins |
无 |
加入页面流水线的
Textlane 插件，每项为名称或
{ name, options }：md 作用于 Markdown
页面在指令之后的语法树，html 作用于每个页面在生成标题 id
之前的语法树。htmlpress 已运行的插件（如 md.gfm 或
html.slug）会用你的选项重新配置，而不会运行两次；参见
插件。
|
skills |
无 |
一个 glob 或一个 SKILL.md 文件列表，路径相对于项目，作为智能体技能发布
|
languages |
一种，英语 | 站点发布的语言，默认语言在前；参见 翻译 |
设置了 languages 后，读者看到的文本（title、
description、banner，以及链接和分区的标题）也可以接受按语言代码组织的映射，例如
title: { en: Docs, es: Guía }。
完整的 schema 位于
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。
完整示例
大多数实际站点最终看起来都类似这样：
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/下一步
- 站点元数据：标题、描述、favicon、logo。
- 文章分区：将站点划分为拥有独立导航的分区。
- 外部链接：页眉和侧边栏链接。
- 语法主题：代码块的外观。
- 文章补丁：通过配置覆盖页面元数据。
- 覆盖/弹出：替换任何内置的布局、样式表或组件。
- 自定义路由：拥有独立布局的页面。
用 ❤ 和 Htmlpress 构建