Themes

A theme controls how Build Pages output looks and behaves.

Build Pages discovers Markdown, reads optional site config, prepares ZeroPress build data, and passes that data to a ZeroPress theme. The theme provides layouts, partials, CSS, JavaScript, navigation markup, search UI, and other presentation details.

Markdown documents + Build Pages config + ZeroPress theme
  -> static HTML output

Bundled Themes

Use --theme to select a bundled theme.

npx --yes @zeropress/build-pages \
  --source ./docs \
  --destination ./_site \
  --theme docs2

Allowed bundled theme values:

• docs
• docs1
• docs2

docs is the default bundled value and currently aliases docs1.

For rendered previews, example repositories, and theme source links, see zeropress.page.

Bundled theme source files are published in the themes directory.

Custom Themes

Use --theme-path when your project has a local theme directory.

npx --yes @zeropress/build-pages \
  --source ./docs \
  --destination ./_site \
  --theme-path ./theme-docs

--theme-path takes precedence over --theme.

Custom themes use the same fixed safety limits as other ZeroPress theme workflows: 4 MiB in total, 1 MiB per file, and 128 entries. Build Pages reads a custom theme directory through Build Core, so the entry, per-file, and total-size limits apply consistently.

See Theme Package Limits for exact counting rules and asset-placement guidance.

Create A Theme

Use @zeropress/create-theme when you want to scaffold a standalone theme project.

npx @zeropress/create-theme --name my-docs-theme --template docs

The generated theme can be edited locally and passed to Build Pages with --theme-path.

Theme Contract

Build Pages themes are regular ZeroPress themes. They use the same theme.json, template syntax, partials, and asset rules as other ZeroPress themes.

For the full authoring guide, see ZeroPress Theme Authoring.