ZeroPress Logo ZeroPress Docs

Themes And Tools

ZeroPress CLI Tools

Use these commands when creating a theme or building a site outside a starter repository. For a ready-to-deploy site, see Getting Started.

Choose A Tool

Task Package
Create a theme and sample content @zeropress/create-theme
Preview or validate a theme @zeropress/theme
Build from Preview Data and a theme @zeropress/build
Build from Markdown @zeropress/build-pages
Convert a WordPress WXR export to Preview Data @zeropress/wxr-import

Each package README lists its requirements and full command options.

Create A Theme

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

Choose minimal, blog, docs, portfolio, or magazine. The generated project includes theme/ and sample zeropress-preview-data.json.

Preview And Validate

Preview the generated theme locally:

npx @zeropress/theme dev ./my-theme/theme --data ./my-theme/zeropress-preview-data.json

Validate it:

npx @zeropress/theme validate ./my-theme/theme

See Customize a Theme for templates and customization, and Theme Package Limits for file and size requirements.

Build From Preview Data

When you already have a theme and a Preview Data file:

npx @zeropress/build ./theme --data ./zeropress-preview-data.json --out ./dist

Serve dist/ with a static host. See the Preview Data Reference when generating your own data.

Body Size Policy

The builder and WXR importer warn from 256 KiB per post or page. They have no fixed body maximum by default. To set an inclusive UTF-8 byte maximum:

npx @zeropress/build ./theme --data ./zeropress-preview-data.json --out ./dist --max-body-bytes 1048576

This accepts exactly 1 MiB and rejects larger input bodies before output replacement. Use a positive decimal integer; zero, units such as 1MiB, and repeated options are errors. Omit the option to keep the default. JavaScript APIs accept maxBodyBytes, with omission or null meaning no product-level body maximum. The option applies to input content, not final HTML. Memory, format, temporary storage and hosting limits remain in effect. See Content And Input Limits for the separate Static and Studio policies.

Data URI body images

Data URI images are removed by default. For Markdown or other Preview Data content that intentionally embeds raster images, opt in at build time:

npx @zeropress/build ./theme --data ./zeropress-preview-data.json --out ./dist --allow-data-uri-images

The flag takes no value. The equivalent build API option is allowDataUriImages: true. It accepts Base64 PNG, JPEG, GIF and WebP URLs in body Markdown images and HTML img src/srcset, after strict Base64 and matching image-signature checks. SVG, other Data URI resources, widgets, featured images and site logos keep their existing restrictions.

The flag does not extract image files or bypass body-size, search, path or hosting limits. Invalid image URLs are removed and reported once per build as DATA_URI_IMAGES_REMOVED, with counts and reasons, without payloads. Without the flag, this CLI keeps quiet removal. WordPress/WXR and Studio product defaults do not enable it; users managing their own CI/CD can opt in here. Build Pages provides the same CLI flag and the allow-data-uri-images Action input, and also warns on default removal.

Native Search Indexing

Build Core warns when the native search JSON reaches 2 MiB. At 5 MiB or more, or above 5,000 searchable records, it replaces the index with a non-searchable placeholder. The build still succeeds; the native adapter returns no results. Use an external search step such as Pagefind for larger sites.

If an external index will supply search, skip native indexing work explicitly:

npx @zeropress/build ./theme \
  --data ./zeropress-preview-data.json \
  --out ./dist \
  --skip-search-index

--skip-search-index takes no value. Its JavaScript equivalent is generateSearchIndex: false in runBuild() options. It does not run Pagefind or disable the search UI. When search is enabled, search.json, search.js, and search_pagefind.js remain available; a genuinely empty site keeps [].

Preview Data site.search.enabled: false or a theme without features.search: true takes precedence: no search artifacts are emitted, even with --skip-search-index. See Static Search for the complete priority rules, warnings, and Pagefind replacement steps.

To replace an existing build output, also pass --empty-out-dir. Replacement happens only after a successful build, and the output must remain inside the project directory without overlapping build inputs. Preview Data path aliases are resolved when checking whether replacement would remove the input file.

Build From Markdown

For Markdown commands, configuration, and GitHub Action usage, follow the Build Pages guide.

Convert A WordPress Export

For ongoing publishing from the WordPress admin, use ZeroPress Static. The WXR starter runs the importer and builder for the files prepared by the plugin. For a manual export, run:

npx @zeropress/wxr-import --input ./wordpress-export.xml --output ./zeropress-preview-data.json

The importer also accepts --max-body-bytes <bytes>. A configured maximum checks the XML-decoded source body before trimming and the converted content, including media URL expansion. A source body that fits can grow beyond the maximum during conversion. Without the option, warnings remain but there is no fixed body ceiling; other import guards remain active.

Build the resulting file with @zeropress/build and a theme. For a ready-made site that keeps WordPress media and comments, use WXR Starter.

Validators

The build and theme commands validate their inputs. Custom integrations can use @zeropress/preview-data-validator and @zeropress/theme-validator directly. The Reference documents their contracts.