# Article Patches

> Override a page's metadata from your config, without touching the file.

Sometimes a file doubles as site content and a file read elsewhere: a `README.md` GitHub renders, or HTML another project shares. A patch sets its page metadata from `htmlpress.yaml`, so the file stays as it is, the way Livemark's patches set an article's frontmatter.

## Basic usage

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

A patched `.md` file becomes a page: its Markdown (with GitHub's tables, task lists, strikethrough and footnotes) is rendered to HTML and built beside it as an `.html` page, here moved to `/introduction/`. A patched `.html` file must be a page already.

## Fields

`file` is the project-relative path; `article` takes any of the fields a page's [head](/authoring/frontmatter/) sets: `title`, `label`, `description`, `icon`, `order`, `path`, `sidebar`, `breadcrumbs`, `toc`, `image`, `author` (one or a list), `date`, `tags`, `sourceUrl` and `sourceAction`. Any other field is an error, and so is a file that does not exist, one outside the project (by `..` or a symlink), or a dot-file, `node_modules` or `.htmlpress` file: whatever a patch names is published, so secrets such as `.env` never can be.

## Merge semantics

A patch's fields apply on top of the page's own head; anything a patch leaves out keeps its normal value. Relative links inside a moved file are not rewritten, so a README's `docs/guide.md` link still points where it did.

## What you can't patch

The content: the body of a page is always the body of the file.

## See also

- [Frontmatter](/authoring/frontmatter/): the head tags a page sets itself.
- [Config File](/customization/configuration-file/): the `include` glob that decides which files are pages.