Article Patches

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

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 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: the head tags a page sets itself.
• Config File: the include glob that decides which files are pages.