Config File

Updated Nov 1, 2026

The config file is optional. By default htmlpress picks up every .html file in the folder you point it at.

Htmlpress is configured by a single file at the root of your project: htmlpress.yaml. Drop it next to your pages and htmlpress picks it up automatically: no flag, no env var. Its keys follow Livemark's config.

Minimal config

Every key is optional, so a project needs no config at all. The smallest useful one names the site:

title: My docs

An empty htmlpress.yaml is the same as none. Without one, every .html and .md file under the project (default include: ["**/*.html", "**/*.md"]) becomes a page, rendered with the built-in layout and theme: sidebar, table of contents, dark mode, all defaults. Every other file is copied to the output as-is, at the same path. Dot-folders such as .git/ and .htmlpress/, and node_modules/, are skipped.

What you can configure

Every key falls back to a sensible default. The full set:

Key	Default	Use
`include`	`*/.html`, `*/.md`	one glob or a list: the `.html` and `.md` files that become pages; an `.md` beside its `.html` twin is copied instead
`exclude`	none	one glob or a list: files left out of the build entirely, pages or not
`title`	the folder name	the header and every tab title
`description`	none	for pages without their own
`site`	none	the public URL, for canonical and social links and `sitemap.xml`
`base`	none	the sub-path the site is served under, such as `/repo/` on GitHub Pages; see Base path
`logo`	none	an image's URL, shown before the site title
`favicon`	the logo	the site icon's URL
`banner`	none	HTML for an announcement bar above the header
`breadcrumbs`	`true`	the trail of folders above each page's content; a page's `<meta name="breadcrumbs">` overrides it
`head`	none	`meta`, `links` and `scripts` added to every page's head; see Site Metadata
`links`	none	links in the header or the sidebar; see External Links
`sections`	none	parts of the site with a navigation of their own; see Article Sections
`edit`	none	an "Edit on GitHub" link: this URL followed by the page's path
`contentSignals`	all `true`	`search`, `aiInput` and `aiTrain`: how automated systems may use the content, written to `robots.txt`; see AI Agents
`codeThemeLight`, `codeThemeDark`	`catppuccin-latte`, `catppuccin-mocha`	The code block themes; see Syntax Themes.
`patches`	none	Page metadata set from the config, and `.md` files published as pages; see Article Patches.
`plugins`	none	Textlane plugins added to the page pipeline, each a name or `{ name, options }`: `md` on a Markdown page's tree after its directives, `html` on every page's tree before heading ids. A plugin htmlpress already runs, such as `md.gfm` or `html.slug`, is reconfigured with your options instead of running twice; see Plugins.
`skills`	none	one glob or a list of `SKILL.md` files, relative to the project, to publish as agent skills
`languages`	one, English	the languages the site is published in, the default first; see Translations

With languages, the texts a reader sees (title, description, banner, and the titles of links and sections) also take a map by language code, such as title: { en: Docs, es: Guía }.

The full schema lives in rust/src/models/config.rs. An unknown key is an error, so a typo never passes silently.

Include and exclude

include replaces the default, so list every folder you want. Each glob's folders before its first wildcard are its base: only files under a base are read, and they are served without it, so docs/**/*.html builds docs/guide.html to /guide/. Other files under a base, .html ones include leaves out too, are copied as they are.

Globs are relative to the project and cannot leave it (.. or an absolute path is an error): * stays within a folder, ** crosses folders, and an include or exclude pattern that matches no file prints a warning.

Base path

With base set, every root-relative URL in the build (in href, src, srcset, poster and action, in pages, the layout and the config's HTML alike) gets it as a prefix: write /guide/ and the site links to /repo/guide/. Relative and absolute URLs are left alone, and so are url()s in a page's own CSS. start and preview serve the site under the base too, and send / there; restart start after changing base.

Worked example

Most real sites end up looking something like this:

site: https://htmlpress.dev
title: Htmlpress
description: Static site generator
logo: /logo.svg
banner: 'Version 1 is out: <a href="/changelog/">read more</a>'
include: docs/**/*.html
exclude: docs/**/_*
links:
  - title: GitHub
    url: https://github.com/datisthq/htmlpress
  - title: Chat
    url: https://discord.gg/example
    position: sidebar
head:
  scripts:
    - src: https://stats.example.com/script.js
      defer: ""
contentSignals:
  aiTrain: false
skills: .skills/*/SKILL.md
edit: https://github.com/datisthq/htmlpress/edit/main/docs/

Where to go next

Site Metadata: title, description, favicon, logo.
Article Sections: split the site into sections with their own navigation.
External Links: header and sidebar links.
Syntax Themes: the look of code blocks.
Article Patches: override page metadata from config.
Overriding/Escaping: replace any built-in layout, stylesheet or component.
Custom Routes: pages with their own layout.

Created with ❤ and Htmlpress