Configuration and command-line reference

The standard ZeroSite command reads one JSON object. Unknown keys, invalid types and trailing JSON values fail configuration loading. Duplicate JSON keys are accepted by Go's decoder; avoid them because later values can obscure the intended setting. The command's -config and -out paths are resolved from its working directory. Paths within the config are relative to the input repository unless noted otherwise.

Command-line flags

The skill and version subcommands are separate commands, not build flags. -serve builds once and serves the output; rebuild or restart after edits.

Skill and version subcommands

For example, export the skill and inspect the matching generator version:

go run github.com/ornew/zerosite@FULL_COMMIT_SHA skill -out .agents/skills/zerosite
go run github.com/ornew/zerosite@FULL_COMMIT_SHA version

Replace FULL_COMMIT_SHA with the revision used to build the site. The export includes .zerosite-skill and .zerosite-version metadata. The destination must be a dedicated skill directory; unrelated files and symlink destinations are rejected. The source of the embedded skill is the .agents/skills/zerosite/ directory in the selected ZeroSite revision. Keep the exported skill and generator pin together at that revision.

Site identity and deployment

Publication and routes

Glob syntax supports *, ?, character classes, and ** as a whole path segment matching zero or more directories. Braces and negated pattern lists are not supported. README.md and index.md always map to their directory's index.html. All output routes, aliases, assets and generated files are checked for collisions.

Navigation, search, and page layout

Setting redirectRules: false suppresses only the _redirects file; individual redirect HTML pages are still generated. Disabling bundledAssets also removes the assets referenced by the default layout, so provide a compatible custom layout and its assets when turning it off. A file in templates is parsed as a named Go template using its basename and can be called from the layout.

Each sections object supports:

Pages not matched by configured sections form groups from their section metadata, or Other if unset. Pager section stays within the page's section; group spans one top-level section and its descendants; site spans every group. Pages hidden with nav: false are skipped, and a hidden current page has no neighbors. pagerOrder patterns match source paths. Matching pages are ordered by the first matching pattern's position, independently of navigation order; unmatched pages retain their stable order after matched pages.

With directoryLinks: true, directory index pages use trailing-slash routes. When repositoryLinks is enabled, unresolved source links that refer to a repository file or directory prefer the configured repository URL over an incidental published route with the same filename.

tocDepth controls the deepest heading included in a page TOC and search heading list. It must be from 2 through 6. order lists logical source paths; listed paths sort before other pages of the same weight, with earlier entries first.

Search index schema

searchIndex can customize the generated search file and its entry format:

fields may map title, url, text, section, and headings to nonempty output property names; duplicate output property names are rejected. The default three properties are title, url, and text. The headings value is a list of heading ID/title pairs. Search heading entries are included only when searchHeadings is true. headingTitle accepts empty/default or context and heading; headingText accepts empty/default, heading, or page; section accepts empty/default, leaf, or group.

Markdown processing

The markdown object is optional. Unicode IDs lowercase text, keep Unicode letters/digits/marks plus hyphens and underscores, turn whitespace into hyphens, remove other punctuation, and suffix duplicate IDs. Goldmark mode uses Goldmark automatic IDs. The table of contents includes heading levels 2 through 4.

Configuration defaults and metadata

defaults is an ordered array of { "match": ["glob"], "values": { ... } }. Every matching rule applies in order. Built-in defaults apply first, matching configuration rules next, and page front matter last. A later explicit value overrides an earlier value, including false, zero, an empty string, or an empty array.

The same metadata fields are accepted under defaults[].values and as YAML front matter:

Front matter is one YAML mapping between opening and closing --- lines. Unknown keys, duplicate YAML keys, wrong types, or an unclosed mapping fail the build. Excluded files remain excluded regardless of metadata. Hiding a page from navigation or search does not unpublish it.

Record indexes

recordIndexes is an array of virtual Markdown page definitions:

Records are files named NNN-name.md, with numbers sorted numerically; 000 files are skipped unless includeTemplate is true. Configured exclude patterns still apply. Each needs a level-one heading. Metadata is read from single-line list items such as - **Status**: Accepted; required fields must be nonempty. Duplicate record numbers or duplicate configured fields in one record fail. Title is a special column field linking to each record.

The index source is generated in memory and is never created or overwritten on disk. Existing front matter at that source supplies page metadata while the body is generated. The page follows ordinary front matter/default, route, link and fragment handling. Records are limited to pages that pass include/exclude, publication and draft filtering.

Templates and output paths

Custom layouts use Go html/template and receive a View with .Config, .Page, trusted rendered .Body, .Groups, .TOC, .Previous, .Next, asset URLs, .Source, .Canonical, .NoIndex, and .URL. Call .URL for a path relative to the current output page. Generated search, CSS, JS and theme URLs are escaped paths relative to the current output page, which supports deployment under a base path. The default layout and scripts provide responsive navigation, search, and light/dark/system theme selection; a replacement template owns the markup for features it wants to retain.

Markdown links resolve relative to the source path, even for a custom permalink. Local targets and fragments must exist and be published; external links are not checked for availability. Generated output must be new, empty, or contain the ZeroSite ownership marker. Failed builds preserve prior output; successful builds replace it after validation.