# 前置元数据

> 设置页面标题、描述、图片、排序和布局的键，可写成 Markdown 前置元数据或 HTML head 标签。

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

**HTML**

```html
<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>
```

**Markdown**

```md
---
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` 包裹页面，适用于需要不同外观框架的页面，例如不带侧边栏的落地页。布局不存在会导致构建失败；见 [覆盖/弹出](/zh/customization/overriding-escaping/)。 |
| `label`       | 标题                 | 页面导航条目的简短名称。                                                                                                                        |
| `icon`        | 无                  | 显示在顶层导航条目前的[内置图标](/zh/authoring/rich-elements/)，或用于索引页所在文件夹的分组；文件夹内的页面不显示图标。未知的名称会导致构建失败。                                           |
| `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。见 [链接](/zh/authoring/links/)。

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

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

## 无需编辑即可覆盖

这里的每个字段也可以在 `htmlpress.yaml` 中设置，无需改动文件本身；见 [文章补丁](/zh/customization/article-patches/)。

## 另请参阅

- [文章分区](/zh/customization/article-sections/) — 文件夹如何在导航中对页面分组。
- [文章补丁](/zh/customization/article-patches/) — 通过配置设置页面元数据。