zeropress.dev

ZeroPress Theme Runtime Spec v0.2

Status: Superseded by v0.3

This document is kept for historical reference only. New validation, upload, and submission flows must use v0.3: Theme Runtime v0.3

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

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 required.
• assets/theme.js is optional and is not auto-executed by the runtime contract.
• archive.html, category.html, and tag.html are optional capabilities. If a theme omits them, related route outputs are omitted even when preview-data still contains those route arrays.
• 404.html is optional. When present, build tooling may emit a 404.html artifact; when absent, that artifact is omitted.
• Upload ZIPs may be root-flat or wrapped in one top-level folder.

3. theme.json v0.2

Minimal example:

{
  "name": "My Theme",
  "namespace": "your-namespace",
  "slug": "my-theme",
  "version": "0.2.0",
  "license": "MIT",
  "description": "A ZeroPress theme.",
  "runtime": "0.2"
}

Required fields:

• name (string, 1-80 chars)
• namespace (string, 3-24 chars)
• slug (string, 3-32 chars)
• version (semver)
• license (enum)
• runtime (must be "0.2")

Optional fields:

• author (string, 1-80 chars if present)
• description (string, up to 280 chars)

License enum:

• MIT
• Apache-2.0
• BSD-3-Clause
• GPL-3.0-only
• GPL-3.0-or-later

Identity rules:

• namespace and slug must follow the ZeroPress package naming rules
• namespace must match the registered publisher namespace in directory-backed submission flows
• slug is the canonical theme identifier within a namespace

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 build-generated data injection.
• JavaScript is for progressive enhancement, not core rendering.
• Preview-data stays canonical and data-only; build tooling computes theme-facing render data immediately before template rendering.
• Runtime data may include richer HTML-ready fields on post objects.
• `` is supported as an optional rendered HTML fragment for post comment sections.

6. Security and Packaging Rules

• Tooling does not execute theme code.
• Path escape is forbidden.
• 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
• Missing required manifest fields
• Invalid version semver
• Invalid license
• runtime not equal to "0.2"
• Invalid namespace or slug
• layout.html slot rule violations
• Disallowed template syntax patterns

Warnings:

• Missing optional templates: archive.html, category.html, tag.html
• post.html missing ``
• `` used outside post.html

Runtime behavior:

• Required preview-data route arrays do not guarantee emitted artifacts for optional route kinds.
• archive, category, and tag pages are emitted only when both renderable route data exists and the matching template exists.
• 404.html is emitted only when the theme provides a 404.html template.

8. CLI Alignment

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

9. Compatibility Notes

• v0.2 is kept for historical reference only.
• New validation and upload flows must use v0.3.

10. Toolkit Baseline

• Node.js: >= 18.18.0
• ESM only
• CommonJS is not supported

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.namespace, theme.json.slug, theme.json.version, theme.json.license, theme.json.runtime	Normative (Required)	Must be present and valid
theme.json.author	Informative (Optional)	Optional package display metadata
theme.json.description	Informative (Optional)	Recommended metadata for theme clarity
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
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
partials/ directory	Informative (Optional)	Supported but not required
assets/theme.js	Informative (Optional)	Optional file; not auto-executed

This site is open source. Improve this page.