# 文章补丁

> 通过配置覆盖页面的元数据，而无需改动文件本身。

有时一个文件既是站点内容，又会在别处被读取：比如 GitHub 渲染的 `README.md`，或其他项目共享的 HTML。补丁通过 `htmlpress.yaml` 设置它的页面元数据，让文件保持原样，就像 Livemark 的补丁设置文章的 frontmatter 一样。

## 基本用法

```yaml
patches:
  - file: README.md
    article:
      title: Introduction
      description: Set up your first project.
      path: /introduction/
      order: 1
  - file: guides/shared.html
    article:
      sidebar: false
```

打过补丁的 `.md` 文件会成为页面：它的 Markdown（支持 GitHub 的表格、任务列表、删除线和脚注）被渲染为 HTML，并在其旁边构建为一个 `.html` 页面，此例中移动到了 `/introduction/`。打补丁的 `.html` 文件本身必须已经是页面。

## 字段

`file` 是相对于项目的路径；`article` 接受页面 [head](/zh/authoring/frontmatter/) 可设置的任何字段： `title`、`label`、`description`、`icon`、 `order`、`path`、`sidebar`、`breadcrumbs`、`toc`、 `image`、`author`（单个或列表）、`date`、 `tags`、`sourceUrl` 和 `sourceAction`。其他任何字段都会报错；文件不存在、位于项目之外（通过 `..` 或符号链接），或是点文件、`node_modules` 或 `.htmlpress` 中的文件，同样会报错：补丁指定的任何文件都会被发布，因此像 `.env` 这样的机密文件绝不能被发布。

## 合并语义

补丁的字段叠加在页面自身的 head 之上；补丁未设置的字段保持原值。被移动文件中的相对链接不会被重写，所以 README 中的 `docs/guide.md` 链接仍指向原来的位置。

## 不能打补丁的内容

内容本身：页面的正文始终是文件的正文。

## 另请参阅

- [Frontmatter](/zh/authoring/frontmatter/)：页面自身设置的 head 标签。
- [配置文件](/zh/customization/configuration-file/)：决定哪些文件成为页面的 `include` glob。