zeropress.dev

ZeroPress Theme Runtime Spec v0.1

Status: Active (aligned with the current runtime and CLI toolchain)

0. Core Philosophy

• Themes define structure, not application behavior.
• A theme bundle is a file-only artifact.
• Tooling (dev, validate, pack) is external to the runtime contract.
• Themes must render meaningful HTML even without JavaScript.

1. Scope

A ZeroPress theme is responsible only for:

• HTML templates
• CSS and static assets
• Theme metadata (theme.json)

Out of scope:

• Backend APIs, authentication, and admin features
• Client-side routing-dependent app architecture
• Runtime logic-centric application behavior

2. Runtime Contract (Current)

Baseline structure compatible with current build/upload pipelines:

my-theme/
  theme.json
  layout.html
  index.html
  post.html
  page.html
  archive.html
  category.html
  tag.html
  404.html (optional)
  partials/
    *.html
  assets/
    style.css
    theme.js (optional)

Key points:

• Template files are expected as root-level .html files.
• partials/ is optional.
• assets/style.css is effectively required.
• assets/theme.js is optional and is not auto-executed by the runtime contract.
• Upload ZIPs may be root-flat or wrapped in one top-level folder (basePrefix).

2.1 Optional Devtools Layer

Using create-zeropress-theme --with-devtools may add local development files (for example, package.json) to the theme directory.

Important:

• This is a local convenience layer and does not change the runtime contract.
• Final upload ZIP validation is based on pure theme files.
• node_modules and lockfiles are excluded from packaging.
• Devtools scripts are thin wrappers around zeropress-theme commands (no extra local dependencies required by default).

3. theme.json (Current)

Minimal example:

{
  "name": "my-theme",
  "version": "0.1.0",
  "author": "Author Name",
  "description": "Theme description"
}

Required fields:

• name (string)
• version (semver)
• author (string)

Recommended field:

• description (string)

4. Template Rules

• layout.html must include exactly one ``.
• Allowed slot names: content, header, footer, meta.
• Nested slot expressions are not allowed.
• <script> tags are not allowed in layout.html.
• Mustache block syntax is not allowed (,).

5. Variables and Rendering

• Only simple variable substitution is supported.
• Rendering is designed for server-prepared data injection.
• JavaScript is for progressive enhancement, not core rendering.

6. Security and Packaging Rules

• Tooling does not execute theme code.
• Path escape is forbidden (for example, ../ or absolute path traversal).
• Symlink-based root escape is forbidden.
• Distribution unit is a ZIP archive.

Commonly excluded files:

• .git
• node_modules
• dist
• *.log
• __MACOSX, .DS_Store
• package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb

7. Validation Profile

Errors:

• Missing theme.json or invalid JSON
• Missing required templates (layout.html, index.html, post.html, page.html)
• Missing assets/style.css
• Invalid version semver
• layout.html slot rule violations
• Disallowed template syntax patterns (for example, ,)

Warnings:

• Missing optional templates: archive.html, category.html, tag.html

8. CLI Alignment

npx zeropress-theme validate, pack, and dev use this runtime contract as the baseline.

9. Compatibility Notes

• pack generates root-flat ZIP output by default.
• Upload validation also accepts a single-folder wrapped root for user convenience.

10. Toolkit Baseline

• Node.js: >= 18.18.0
• ESM only
• CommonJS is not supported
• No compatibility polyfills for lower Node versions

Initial package versions:

• create-zeropress-theme@0.1.0
• zeropress-theme@0.1.0

11. Normative vs Informative Summary

Item	Classification	Notes
theme.json, layout.html, index.html, post.html, page.html, assets/style.css	Normative (Required)	Missing files produce validation errors
theme.json.name, theme.json.version, theme.json.author	Normative (Required)	Must be non-empty strings; version must be semver
layout.html must contain exactly one ``	Normative (Required)	Validation error if violated
Allowed slots: content, header, footer, meta	Normative (Required)	Unknown slots are invalid
No <script> in layout.html	Normative (Required)	Validation error in standard checks
Mustache block syntax forbidden (,)	Normative (Required)	Validation error
Path/symlink root escape forbidden	Normative (Required)	Validation error
archive.html, category.html, tag.html	Informative (Recommended)	Missing files produce warnings, not errors
theme.json.description	Informative (Recommended)	Recommended metadata for better theme clarity
partials/ directory	Informative (Optional)	Supported but not required by runtime contract
assets/theme.js	Informative (Optional)	Optional file; not auto-executed by runtime contract
Devtools files (package.json, scripts, lockfiles)	Informative (Local tooling layer)	Useful for local workflows; excluded from packaging

This site is open source. Improve this page.