Plugins

Updated Nov 1, 2026

Every page builds through textlane, a Rust Markdown and HTML pipeline. The plugins key of htmlpress.yaml adds textlane's own plugins to it, in two slots:

md runs on a Markdown page's tree (mdast)
html runs on every page's tree (hast), HTML and Markdown alike

htmlpress.yaml

plugins:
  md:
    - name: md.shiftHeading
      options: { shift: 1 }
  html:
    - name: html.externalLinks
      options: { target: _blank }

What a plugin can be

Each slot is a list whose entries take the same forms as textlane's use:

A name: one of the plugins textlane ships, such as html.externalLinks or md.toc, with its defaults.
A name with options: { name, options }, the options as textlane documents them for that plugin.

Htmlpress is one binary, so a slot takes only the plugins built into it, and no JavaScript plugins as Livemark does. For markup of your own, add a project component instead: a :::name directive or an <htmlpress-name> tag that your components/<name>/ files fill.

Where each slot runs

Markdown page: parse → frontmatter, GFM, definition lists, math, directives
  → md plugins → heading ids, components → HTML
Every page:    parse → emoji, links, math → KaTeX → html plugins
  → heading slugs → path rewrites → syntax highlighting

md plugins run before htmlpress renders directives as components, so they see every directive.
html plugins run before heading slugs, so a heading a plugin adds gets an anchor and appears in the "On this page" outline. They run before syntax highlighting, so code blocks still hold their plain text.

A plugin htmlpress already runs

Naming a plugin that is already in the pipeline, such as md.gfm or html.slug, reconfigures it rather than running it twice: your options are merged into htmlpress' own, as textlane's use merges a plugin used again. Where htmlpress sets the same option, its value wins, since its plugins are added after yours.

htmlpress.yaml

plugins:
  html:
    - name: html.slug
      options: { prefix: doc- }

Here every generated heading id gets the doc- prefix, and headings still get their ids once.

Errors and rebuilds

An unknown name or bad options fail the build with a plugins.md or plugins.html error, and so does a plugin whose tree does not fit its slot, such as md.toHtml under html. Editing htmlpress.yaml while htmlpress start runs rebuilds every page with the new plugins.