Configuration

The configuration is one PHP file returning one array. It holds data only: no classes, no environment lookups, no side effects. It is optional: every key has a default, so a project directory with a content/ folder builds without one. pholio init writes a small pholio.config.php, and pholio.config.example.php in the repository root shows every key with comments.

Pholio looks for the configuration in this order: the file passed with --config; otherwise pholio.config.php in the project directory (the [dir] argument, default the current directory); otherwise the defaults, with paths relative to the project directory. --config together with a [dir] argument is a usage error.

src/Config.php validates the file before anything is built. An unknown key, a value of the wrong type or a planned key set to anything but its default stops the command with exit code 2 and names the key path, for example pholio: unknown key: search.tokenize (did you mean "tokenizer"?).

Rules for values

Paths (content_dir, output_dir, copy sources, content.asset_root, theme.palette_css, redirects_file) are absolute or relative to the directory of the configuration file, not to the directory you run pholio from.

URL paths start with /. Trailing slashes are optional and removed: every generated URL has none, except the site root /. A URL with a scheme (https://…) is kept as written.

Placeholders are resolved in URL and text values:

• {site}: the title
• {home}: the start page URL, from base_path
• {docs}: the docs root URL, from docs_path
• {assets}: the theme asset URL, from asset_base

Planned keys are part of the schema so a configuration that uses them fails with a clear planned: <key> message instead of unknown key. They accept only their default value until the feature exists.

Site

When a start page is configured and docs_path equals base_path, a content page at the docs root would collide with the start page. The build stops and asks for docs_root_suffix, a different docs_path, or home => null.

Input and output

Rewriting happens at a path boundary only: /handbook matches /handbook and /handbook/guide, never /handbooks.

Navigation

nav is the list of header links, rendered in the header and in the mobile drawer.

Start page

home describes the landing page at base_path. Leave it null to make the first content page the root.

Theme

The theme has a light and a dark color scheme with static colors. theme.light and theme.dark map single color token names, without the --color-fd- prefix, to CSS colors, and theme.palette_css adds a stylesheet of your own. The build writes the token maps and then the stylesheet at the palette marker /* @pholio:palette */ in theme/css/tokens.css. The block is unlayered, so it wins over the default tokens, and the stylesheet wins over the token maps. Anything you leave out keeps its default.

The tokens are background, foreground, muted, muted-foreground, popover, popover-foreground, card, card-foreground, border, primary, primary-foreground, secondary, secondary-foreground, accent, accent-foreground and ring.

'theme' => [
    'light' => ['primary' => 'hsl(220 85% 45%)'],
    'dark' => ['primary' => 'hsl(220 90% 70%)'],
],

Document head

Search

The index is written at build time and loaded by the browser the first time the search dialog opens.

Both tokenizers lowercase, fold diacritics and ligatures (ä → a, ß → ss), split at everything but letters and digits and also index hyphenated words joined, so "chat export", "chat-export" and "chatexport" find the same page. german additionally reads ae, oe and ue as a, o and u, so "Passwörter" and "Passwoerter" meet. Queries drop common stopwords ("wie", "ich", "the", …; german drops German and English ones) unless nothing else is left, and match inflected forms loosely, so "logs" also finds "Logging". Words a page does not use itself can be added with the keywords frontmatter key.

Server

The generated .htaccess is the only server file Pholio writes. It sets security headers and MIME types, maps slashless page URLs to their index.html, and turns every redirect into a 301 rule. A redirect's from must lie below base_path, and its to must be a path.

Agents

What a build publishes for AI agents: a Markdown twin of every page, llms.txt, llms-full.txt, skill.md, the agent card, robots.txt, sitemap.xml, JSON-LD and the discovery headers. Agents describes each file.

A page with noindex: true in its frontmatter is still built, but left out of llms.txt, llms-full.txt, skill.md and sitemap.xml, and gets <meta name="robots" content="noindex">.

Profiles

--profile <name> merges that partial configuration recursively over the base before validation, for example a staging build under another base_path. Unknown keys inside every profile are errors even when the profile isn't selected, and profiles can't be nested.

Extension points