# Config File

> Where the htmlpress config lives, what it controls, and a tour of the top-level options.

> **Info**
>
> 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](https://livemark.dev)'s config.

## Minimal config

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

```yaml
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](#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](/customization/site-metadata/)                                                                                                                                                                                                                                                                        |
| `links`                           | none                                   | links in the header or the sidebar; see [External Links](/customization/external-links/)                                                                                                                                                                                                                                                                                            |
| `sections`                        | none                                   | parts of the site with a navigation of their own; see [Article Sections](/customization/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](/customization/ai-agents/)                                                                                                                                                                                                                                   |
| `codeThemeLight`, `codeThemeDark` | `catppuccin-latte`, `catppuccin-mocha` | The code block themes; see [Syntax Themes](/customization/syntax-themes/).                                                                                                                                                                                                                                                                                                          |
| `patches`                         | none                                   | Page metadata set from the config, and `.md` files published as pages; see [Article Patches](/customization/article-patches/).                                                                                                                                                                                                                                                      |
| `plugins`                         | none                                   | [Textlane](https://textlane.dev) 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](/customization/plugins/). |
| `skills`                          | none                                   | one glob or a list of `SKILL.md` files, relative to the project, to publish as [agent skills](/customization/ai-agents/)                                                                                                                                                                                                                                                            |
| `languages`                       | one, English                           | the languages the site is published in, the default first; see [Translations](/customization/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`](https://github.com/datisthq/htmlpress/blob/main/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:

```yaml
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](/customization/site-metadata/): title, description, favicon, logo.
- [Article Sections](/customization/article-sections/): split the site into sections with their own navigation.
- [External Links](/customization/external-links/): header and sidebar links.
- [Syntax Themes](/customization/syntax-themes/): the look of code blocks.
- [Article Patches](/customization/article-patches/): override page metadata from config.
- [Overriding/Escaping](/customization/overriding-escaping/): replace any built-in layout, stylesheet or component.
- [Custom Routes](/customization/custom-routes/): pages with their own layout.