Guides
ZeroPress CLI Tools
ZeroPress provides a small set of command line tools for creating themes, checking theme packages, previewing local work, and building static site output.
These tools support the Preview Data v0.7 publishing workflow and Theme Runtime v0.7. They are not runtime contracts themselves, but they are the recommended way to work with those contracts.
Choose The Tool
| Goal | Tool |
|---|---|
| Create a starter theme and fixture preview-data | @zeropress/create-theme |
| Preview, validate, or package a theme | @zeropress/theme |
Build directly from preview-data.json and theme/ |
@zeropress/build |
| Build a Markdown source tree for static hosting | @zeropress/build-pages |
Markdown Sites
Use @zeropress/build-pages when a repository contains Markdown files, public assets, and optional .zeropress/config.json. Build Pages is documented separately at build-pages.zeropress.dev.
An authored config file uses the strict Build Pages Config v0.7 Schema and must declare "version": "0.7". If the default config path does not exist, Build Pages continues with its documented defaults; a missing path supplied explicitly with --config is an error. The resolved config always records the v0.7 schema URL and version: "0.7".
As a temporary CLI-only migration path, an explicit version: "0.1" config is accepted with one warning and normalized into the v0.7 model. This does not make v0.1 schema-valid. Only that compatibility path translates historical site.indexing into site.robots: { "allow_indexing": boolean }; v0.7 rejects site.indexing, a missing version, non-string versions, and every other version.
Build Pages validates source-relative file paths against controls, backslashes, traversal, and empty/dot segments. Menu URLs use the Preview Data navigation policy: safe single-slash root-relative or credential-free HTTP(S) only. Omitted menus materializes a primary menu containing Home, while an explicit {} opts out. An omitted menu name uses its menu id, and an omitted collection title uses its collection id. These deterministic fallbacks are recorded in the resolved config before Preview Data is generated.
Theme Development
Create a starter theme:
npx @zeropress/create-theme --name my-docs-theme --template docs
Preview the generated theme:
npx @zeropress/theme dev ./my-docs-theme/theme --data ./my-docs-theme/preview-data.json
Validate and package the theme:
npx @zeropress/theme validate ./my-docs-theme/theme
npx @zeropress/theme pack ./my-docs-theme/theme
The old unscoped create-zeropress-theme package is deprecated. Use @zeropress/create-theme for new projects.
Direct Preview Data Builds
Use @zeropress/build when you already have a v0.7 preview-data.json file and a ZeroPress theme:
npx @zeropress/build ./theme --data ./preview-data.json --out ./dist
This path is useful for AI-generated sites, admin-generated preview-data, importers, and custom pipelines.
Package References
For copy-paste command snippets, see Package Quick Starts.
The package READMEs are the source of truth for command options and release metadata: