前置元数据

更新于 2026年11月1日

页面的元数据是一组键，两种格式中相同。Markdown 页面把它们写成 YAML 前置元数据；HTML 页面写在 <head> 中：title 写作 <title>，其他键写作 <meta name="键" content="…">。页面可以是完整文档，也可以是片段，htmlpress 以相同方式读取两者。每个键都是可选的；缺少某个键时，htmlpress 会根据文件推导出合理的默认值。

<title>Getting started</title>
<meta name="description" content="Install and run it.">
<meta name="order" content="1">

<h1>Getting started</h1>
<p>Plain HTML, styled by the theme.</p>

---
title: Getting started
description: Install and run it.
order: 1
---

# Getting started

Plain Markdown, styled by the theme.

body 会成为布局内的页面内容。每个页面应有一个 title 和一个一级标题。

文章元数据

页面的标识与呈现。

键	默认值	用途
`title`	第一个 `<h1>`，否则为文件名	在导航和浏览器标签页中显示的页面名称。
`description`	`htmlpress.yaml` 中的 `description`	供搜索引擎和社交预览使用的页面描述。
`image`	无	页面被分享时显示的图片，即 `og:image`。相对 URL 从页面的源文件解析；本地图片需要 `site` 才能转为绝对 URL，否则省略。
`head`	无	仅限 Markdown：添加到布局 head 中的原始 HTML，位于主题之后。HTML 页面把自己的 `<link>`、`<style>` 或 `<script>` 写在 `<head>` 中，或写在第一段内容之前，并以同样方式添加。
`date`	无	页面的发布日期，格式为 `YYYY-MM-DD`（时间戳会被截取为日期；其他格式会报错）。显示在标题下方，并用于博客排序。
`author`	无	显示在标题下方的作者；有多位作者时写成列表，或重复该标签。
`keywords`	无	标签，写成列表或用逗号分隔；在博客中每个标签都有一个列出其文章的页面。

当项目位于 git 仓库中时，页面 <h1> 下方的那一行还会根据 git log 显示文件最后修改的时间；同一日期也会作为页面在 sitemap.xml 中的 <lastmod>。

侧边栏设置

页面在导航中的显示方式。

键	默认值	用途
`order`	无（按路径排序）	整数排序位置；见下文“排序规则”。
`layout`	站点布局	改用 `.htmlpress/layouts/<name>.html` 包裹页面，适用于需要不同外观框架的页面，例如不带侧边栏的落地页。布局不存在会导致构建失败；见覆盖/弹出。
`label`	标题	页面导航条目的简短名称。
`icon`	无	显示在顶层导航条目前的内置图标，或用于索引页所在文件夹的分组；文件夹内的页面不显示图标。未知的名称会导致构建失败。
`sidebar`	`true`	`false` 将页面排除在导航以及上一页和下一页链接之外；页面仍会被构建，并可通过其 URL 访问。
`toc`	`true`	`false` 关闭页面的目录。
`breadcrumbs`	配置中的 `breadcrumbs`	`false` 隐藏内容上方的文件夹路径；`true` 即使配置关闭也会显示。
`source-url`	`edit` 加上页面路径	页面源码链接的目标地址，适用于源码存放在别处的页面；值为 `view` 的 `source-action` 会把链接文字从“编辑此页”改为“查看源码”。

排序规则

根目录的 index.html 始终排在最前。
其次是 order 为 0 或更大的页面，按升序排列。
然后是没有 order 的页面，按路径排列。
order 为负数的页面排在最后，因此 -1 会把页面固定在最末尾，-2 紧挨在它之前。

order 决定页面在同级页面中的位置：页面嵌套在其文件夹的 index.html 之下；文件夹位于该页面的 order 所指定的位置，未设置时则位于其第一个页面应在的位置。

非整数的 order 会导致构建失败。根目录下的 404.html 是托管服务在 URL 不存在时显示的页面；它不会出现在导航中，没有该页面的项目会获得一个内置的“页面未找到”页面。

URL

页面在以其文件命名的文件夹处提供服务，guides/build.html 对应 /guides/build/，index.html 则在其自身所在文件夹提供： guides/index.html 对应 /guides/，每个名称都会转换为 slug。见链接。

path: /start/ 让页面在另一个 URL 提供服务，与其文件路径无关：以 / 结尾的路径指向该文件夹，以 .html 结尾的路径则指向该文件所对应的页面，因此 /start.html 同样会在 /start/ 提供该页面。两个页面使用同一个 URL 会导致构建失败。

在设置了 languages 的站点上，名为 guide.es.html 的文件，或带有 language: es 的文件，就是 guide.html 的西班牙语翻译，在 /es/guide/ 提供服务；见翻译。

无需编辑即可覆盖

这里的每个字段也可以在 htmlpress.yaml 中设置，无需改动文件本身；见文章补丁。

另请参阅

文章分区 — 文件夹如何在导航中对页面分组。
文章补丁 — 通过配置设置页面元数据。

用 ❤ 和 Htmlpress 构建