# ZeroPress Theme Authoring ZeroPress themes are static template packages for the current `runtime: "0.5"` contract. A theme decides how ZeroPress content looks and behaves in the browser. The build pipeline prepares structured data, renders Markdown content, resolves widgets, copies theme assets, and emits static output. The theme owns the HTML templates, CSS, and optional client-side enhancement. ## What A Theme Contains A minimal theme directory contains: ```txt my-theme/ theme.json layout.html index.html post.html page.html assets/ style.css ``` Common optional files: ```txt my-theme/ archive.html category.html tag.html 404.html partials/ *.html assets/ theme.js ``` Required files for a usable v0.5 theme: - `theme.json` - `layout.html` - `index.html` - `post.html` - `page.html` - `assets/style.css` ## ZeroPress Site Shape When creating a complete ZeroPress site, the practical authoring unit is: ```txt my-site/ preview-data.json theme/ theme.json layout.html index.html post.html page.html partials/ tracker.html content-enhancements.html assets/ style.css theme.js public/ favicon.ico vendor/ ``` - `preview-data.json` defines site data, content, menus, widgets, and permalink policy. - `theme/` defines deterministic rendering through the v0.5 theme runtime. - `theme/assets/` contains theme-owned CSS and JavaScript referenced by the theme. - `public/` contains site-owned passthrough files such as favicons, PDFs, source files, and third-party vendor assets. Reusable themes should avoid hard-coding site-specific analytics tokens, vendor URLs, or product copy. Prefer a documented partial or `public/` integration point that a site owner can fill. ## `theme.json` The theme manifest identifies the package and declares the v0.5 runtime. ```json { "$schema": "./theme.v0.5.runtime.schema.json", "name": "My Theme", "namespace": "your-namespace", "slug": "my-theme", "version": "0.5.0", "license": "MIT", "runtime": "0.5", "description": "Short summary of the theme.", "features": { "comments": true, "newsletter": true, "postIndex": true }, "menuSlots": { "primary": { "title": "Primary Menu", "description": "Main navigation menu" } }, "widgetAreas": { "sidebar": { "title": "Sidebar Widgets", "description": "Sidebar widget area" } } } ``` The current runtime accepts only `runtime: "0.5"`. There is no fallback to older theme runtimes. Use the [Theme Manifest Runtime v0.5 schema](/schemas/theme.v0.5.runtime.schema.json) as the source of truth for manifest fields. ## Templates And Partials ZeroPress renders one route template inside `layout.html`. - `layout.html` defines the shared document shell. - `index.html` renders the front page, post index, or combined default root route. - `post.html` renders an individual post. - `page.html` renders an individual page. - `archive.html`, `category.html`, `tag.html`, and `404.html` are optional route templates. - `partials/*.html` are reusable template fragments. The layout must include the content slot: ```html
{{slot:content}}
``` Common helpers: ```html {{menu:primary}} {{partial:header}} {{partial:post-card variant="compact" show_excerpt=true}} ``` Template syntax supports variables, `if`, `if_eq`, `else_if`, `else_if_eq`, `for`, loop metadata, partial arguments, and template comments. See [Theme Runtime v0.5](../spec/theme-runtime-v0.5.md) for the full contract. If a theme needs to iterate a menu manually, use `menus..items` with the same slot id declared in `theme.json`. Both plain ids such as `primary` and hyphenated ids such as `docs-sidebar` are valid: ```html {{#for section in menus.docs-sidebar.items}}

{{section.title}}

{{/for}} ``` For example, `menus.primary.items` and `menus.docs-sidebar.items` are both valid. Hyphens must stay inside a path segment, so `menus.-docs.items`, `menus.docs-.items`, and `menus.docs--sidebar.items` are invalid. ## Common Render Context Every rendered template receives common build data: - `site` - `currentUrl` - `language` - `route` - `menus` - `widgets` - `meta` - `taxonomies.categories[]` - `taxonomies.tags[]` Global taxonomy items are generated by build for theme rendering. They are useful for home filters, sidebars, tag clouds, and navigation chips without scanning post card attributes in client JavaScript. Each taxonomy item provides: - `name` - `slug` - `url` - `count` - `description` The `url` field follows the active permalink policy. Declared categories and tags remain present even when `count` is `0`, so themes can decide whether to show or hide empty taxonomy links. ```html ``` ## Route Data Build output exposes structured route data to templates. Post lists should render from: - `posts.items[]` - `pagination` The `route` object identifies the current render target: - `route.type` - `route.is_front_page` - `route.is_post_index` - `route.path` - `route.url` Use `route.is_post_index` before rendering post-index-only UI. Use `pagination.enabled` before rendering page navigation. A site may request a non-paginated post index, and a theme may declare `"postIndex": false` to opt out of post index rendering entirely. When a site uses a page as the front page, the selected page is rendered at `/` through `page.html`, and its normal page route is not emitted. The root render has `route.type: "front_page"` and `route.is_front_page: true`. Use that flag when front-page markup should differ from normal document pages. Category and tag routes also receive: - `taxonomy.kind` - `taxonomy.slug` - `taxonomy.name` - `taxonomy.count` Posts should render from fields such as: - `post.title` - `post.url` - `post.excerpt` - `post.featured_image` - `post.html` - `post.published_at` - `post.updated_at` - `post.reading_time` - `post.author` - `post.categories[]` - `post.tags[]` - `post.prev` - `post.next` - `post.comments_enabled` - `post.toc[]` Pages should render from fields such as: - `page.title` - `page.html` - `page.toc[]` For Markdown-first document pages, remember that `page.html` is the rendered Markdown body. If the source Markdown starts with `# Title`, then `page.html` already contains that H1. In that case, do not render a second `

{{page.title}}

` in `page.html`; use the body HTML as the document heading source. Front pages often use Markdown that already starts with an H1. A simple pattern is: ```html {{#if route.is_front_page}}
{{page.html}}
{{#else}}

{{page.title}}

{{page.html}}
{{/if}} ``` ## Menus And Widgets Menus are declared by preview data and rendered by theme templates through menu helpers: ```html ``` Widget areas are resolved before template rendering. Themes should consume the resolved widget data, not raw widget settings. Example: ```html {{#if widgets.sidebar.items}} {{/if}} ``` ## Markdown Content And TOC For `document_type: "markdown"`, ZeroPress renders Markdown to HTML and assigns stable `id` attributes to headings. Markdown pages and posts also receive generated TOC data: - `level` - `id` - `title` - `href` Example: ```html {{#if page.toc}} {{/if}} ``` Heading anchor UI is optional theme UI. Build output provides heading ids and TOC data, but it does not wrap heading text in permalink anchors. Markdown rendering also includes common authoring conventions that themes may style: - GFM tables render as `` markup. - `~~deleted~~` renders as `deleted`. - Task lists render disabled checkbox inputs and use `contains-task-list`, `task-list-item`, and `task-list-item-checkbox` classes. - GitHub alert blockquotes such as `> [!NOTE]` render as `