Themes And Tools
Media and Integrations
Keep content readable in HTML and CSS. Add JavaScript where an integration needs interaction, such as search results or a comments form.
Images
Preview Data media fields, including featured images, avatars, and logos, accept credential-free HTTP(S) URLs with a non-root path, or root-relative paths:
https://media.example.com/photo.jpg/images/photo.jpg
Bare or dot-relative paths such as images/photo.jpg and ./images/photo.jpg
are invalid for these fields. A root-relative path resolves against
site.media_origin when set; otherwise it stays root-relative to the public site. For example, public/images/photo.jpg can be referenced as /images/photo.jpg when site.media_origin is empty.
When Preview Data includes matching media metadata, use it for dimensions and alternative text. Managed raster images can also provide srcset when media-domain delivery is configured:
{{#if post.featured_media.srcset}}
<img
src="{{post.featured_image}}"
srcset="{{post.featured_media.srcset}}"
sizes="(min-width: 900px) 720px, 100vw"
width="{{post.featured_media.width}}"
height="{{post.featured_media.height}}"
alt="{{post.featured_media.alt}}"
loading="lazy"
decoding="async"
>
{{#else_if post.featured_image}}
<img src="{{post.featured_image}}" alt="{{post.featured_media.alt}}" loading="lazy" decoding="async">
{{/if}}
Use page.featured_media for pages and post.author.avatar_media for author images. See media origin and delivery for the delivery settings and media metadata for registry fields. The rendered media companion defines the fields available in templates.
Responsive Images
Use CSS to fit an image inside the content area, srcset and sizes to offer different resolutions, and <picture> to select a different composition. These browser features work without JavaScript.
Put site-owned images in public/ and reusable CSS in theme/assets/. Add this class to the images in the following examples:
.responsive-image {
display: block;
max-width: 100%;
height: auto;
}
Docs2 already limits content images to the available width and preserves their aspect ratio. Add class="aligncenter" to an <img> to center a standalone diagram or screenshot within the content column, including inside <picture>. This does not enlarge a small image or change other images’ alignment.
Keep width and height proportional to the image’s intrinsic dimensions so the browser can reserve space. Use meaningful alt text on the <img>; a decorative image can use alt="".
Choose an image resolution
For the same photograph at several sizes, provide the files and list their actual pixel widths. This example assumes an image displayed at up to 720 CSS pixels, with 16 pixels of space on each side of a narrow viewport:
.responsive-photo {
width: min(720px, calc(100vw - 32px));
}
<img
class="responsive-image responsive-photo"
src="/images/photo-960.jpg"
srcset="/images/photo-480.jpg 480w, /images/photo-960.jpg 960w, /images/photo-1440.jpg 1440w"
sizes="(min-width: 752px) 720px, calc(100vw - 32px)"
width="960"
height="640"
alt="A mountain reflected in a lake"
loading="lazy"
decoding="async"
>
The browser selects a candidate using the expected display width and factors such as pixel density. It does not necessarily select the same file on every device. Adjust the CSS and sizes together if a sidebar or a narrower content column changes the available space.
Files under public/ are copied as supplied; the builder does not create these three JPEG sizes. The managed-media srcset described above is a separate delivery feature. See MDN’s image attributes for candidate selection details.
Change the composition at a breakpoint
Use <picture> when reducing the same image would make it hard to read. For example, keep a wide flow diagram on desktop and select a vertical version on a narrow screen:
<picture>
<source
media="(max-width: 640px)"
srcset="/diagrams/build-flow-compact.svg"
width="360"
height="374"
>
<img
class="responsive-image"
src="/diagrams/build-flow.svg"
width="720"
height="224"
alt="A theme and Preview Data enter the builder, which produces static files."
>
</picture>
The documentation home combines this width selection with the light/dark variants described below. Provide both files under public/diagrams/ in your own project. The first matching <source> is used; <img> supplies the default image and alternative text. The dimensions on each source preserve the selected image’s aspect ratio.
Light And Dark Images
System preference and a site’s theme selector are different inputs. A browser media query follows the system/browser preference. A theme button can override the page’s appearance without changing that preference.
Follow the system preference
For separate light and dark screenshots, select a file with a media query:
<picture>
<source
media="(prefers-color-scheme: dark)"
srcset="/images/settings-dark.png"
>
<img
class="responsive-image"
src="/images/settings-light.png"
width="960"
height="600"
alt="The site's settings screen"
>
</picture>
Keep these two variants at the same dimensions. This works without JavaScript, but the <source> media condition does not follow a page’s data-theme
attribute. To follow a visitor’s manual choice as well, use the page-CSS selection below. It works with fixed-color SVG, PNG, and JPEG variants;
color-scheme does not recolor PNG or JPEG pixels.
Match the site’s selected theme
The bundled Docs2 theme includes theme-image--light and theme-image--dark for images inside its .prose content area. Put these classes on separate <picture> wrappers. Keep alignment classes such as aligncenter on the inner <img>, so alignment rules cannot make the inactive variant visible. No custom head CSS or additional image-switching script is needed in Docs2.
Provide separate light and dark files with the same content and dimensions. This works with PNG, JPEG, WebP, and fixed-color SVG. For SVG, keep each file’s palette fixed: selecting files in page CSS avoids Safari compatibility issues with color-scheme and media queries inside an external SVG (WebKit issue).
Docs2 sets data-theme="light" or data-theme="dark" on <html>. An explicit site theme takes priority. When the attribute is absent, including with JavaScript disabled, images follow the system preference. A stored manual choice cannot be restored while JavaScript is disabled. Printed pages use the light image to match Docs2’s print stylesheet.
For a screenshot pair, provide public/images/settings-light.png and public/images/settings-dark.png:
<picture class="theme-image--light">
<img class="aligncenter" src="/images/settings-light.png" width="960" height="600" alt="The site's settings screen">
</picture>
<picture class="theme-image--dark">
<img class="aligncenter" src="/images/settings-dark.png" width="960" height="600" alt="The site's settings screen">
</picture>
Add width-based sources to each wrapper when a diagram also needs a compact composition. This is the pattern used on the documentation home:
<picture class="theme-image--light">
<source media="(max-width: 640px)" srcset="/diagrams/build-flow-compact.svg" width="360" height="374">
<img class="aligncenter" src="/diagrams/build-flow.svg" width="720" height="224" alt="A theme and Preview Data enter the builder, which produces static files.">
</picture>
<picture class="theme-image--dark">
<source media="(max-width: 640px)" srcset="/diagrams/build-flow-compact-dark.svg" width="360" height="374">
<img class="aligncenter" src="/diagrams/build-flow-dark.svg" width="720" height="224" alt="A theme and Preview Data enter the builder, which produces static files.">
</picture>
Place all four files under public/diagrams/: build-flow.svg and build-flow-compact.svg are the light versions; the -dark.svg files are their dark counterparts. Each site chooses its files, dimensions, and breakpoint; Docs2 supplies the palette-selection and alignment styles.
Both variants use the same meaningful alt text. display: none removes the inactive picture from the layout and accessibility tree, leaving one visible image and one accessible description. Hiding an image with CSS does not necessarily prevent its download, so keep these variants small.
Add support to another theme
Other themes can implement the same classes in their stylesheet. The example below assumes a .prose content wrapper and data-theme on <html>; adapt the selectors to the theme’s own state and markup. These are theme conventions, not required Theme Runtime fields.
/* Fixed-color image variants opt in through their picture wrapper. */
.prose picture.theme-image--light {
display: block;
}
.prose picture.theme-image--dark {
display: none;
}
@media screen {
:root[data-theme="dark"] .prose picture.theme-image--light {
display: none;
}
:root[data-theme="dark"] .prose picture.theme-image--dark {
display: block;
}
}
@media screen and (prefers-color-scheme: dark) {
:root:not([data-theme]) .prose picture.theme-image--light {
display: none;
}
:root:not([data-theme]) .prose picture.theme-image--dark {
display: block;
}
}
.prose img.aligncenter {
display: block;
max-width: 100%;
height: auto;
margin-inline: auto;
}
The dark rules apply on screen, so printing uses the light variant. Adjust this behavior if the theme has a different print design. Docs2 already includes these styles; use the markup above directly when using Docs2.
Apply and check the examples
For a theme without built-in support, keep the CSS in its stylesheet. A site can also add a stylesheet link or <style> block through trusted custom_html.head_end; Build Pages uses a file reference under the source .zeropress/ directory. This custom CSS step is unnecessary for Docs2’s image variants. See Build Pages custom HTML configuration.
Markdown raw HTML preserves the safe <picture>, <source>, and <img> markup used here. Keep the SVG as an external file and put CSS in the theme or trusted head slot: inline SVG, <style> blocks, and image style attributes inside document bodies are removed by the content sanitizer. Code fences display examples and do not execute them.
Check a wide and a narrow viewport in Chrome and Safari, both system color schemes, and a manual theme choice opposite to the system. Toggle the theme and reload to verify the saved choice. Repeat with JavaScript disabled: the page CSS should select the system’s palette and <picture> should still select the appropriate composition. Confirm that exactly one variant is visible, its aspect ratio and text contrast are correct, and it does not overflow its container. For centered images, check that the left and right space inside the content area are equal. Check print preview for a single light variant.
Markdown Styling
ZeroPress renders tables, task lists, alerts, and highlighted code during the build. Give your content wrapper styles for these elements:
| Content | Selectors |
|---|---|
| Tables and aligned cells | table, th, td, .zp-align-left, .zp-align-center, .zp-align-right |
| Task lists | .contains-task-list, .task-list-item, .task-list-item-checkbox |
| Alerts and admonitions | .zp-alert, .zp-alert--note, .zp-alert--tip, .zp-alert--warning |
| Code | pre, code, .hljs-keyword, .hljs-string, .hljs-comment |
| Media | figure, figcaption, img, video, audio |
For example, keep long code lines scrollable inside the content area:
.prose pre {
max-width: 100%;
overflow-x: auto;
padding: 1rem;
border-radius: 0.5rem;
}
A browser-side syntax highlighter is unnecessary for build-rendered Markdown. Mermaid fences remain code blocks; include a theme script if you want diagrams. The Markdown rendering reference describes supported markup and sanitization.
Table Of Contents
Markdown H2–H4 headings produce page.toc or post.toc entries. Render a Page’s TOC with its generated fragment links:
{{#if page.toc}}
<aside aria-label="Table of contents">
<ol>
{{#for item in page.toc}}
<li class="toc-level-{{item.level}}">
<a href="{{item.href}}">{{item.title}}</a>
</li>
{{/for}}
</ol>
</aside>
{{/if}}
Search And Comments
Use the Static Search guide to connect a search form to native search or Pagefind. A theme with search UI declares features.search: true and checks site.search.enabled before showing it. That value controls search availability; it does not guarantee a populated native index. Explicit indexing skips and automatic size or record limits keep it enabled and leave the UI intact, while the native adapter returns no results. An external search step can replace that adapter. See index generation and limits.
For comments, declare features.comments: true and show the theme’s comments partial only on eligible routes:
{{#if comments.enabled}}
{{partial:comments-island}}
{{/if}}
The partial and its JavaScript connect to the configured provider. site.comments.enabled alone does not establish that a particular Post or Page accepts comments. Use the route’s comments data, described in the route comments contract. The Studio and WXR starters include a comments implementation you can adapt.
Newsletter Links
When Preview Data provides an enabled newsletter with a signup URL, a theme can show a normal link:
{{#if site.newsletter.enabled}}
{{#if site.newsletter.signup_url}}
<a href="{{site.newsletter.signup_url}}">Subscribe</a>
{{/if}}
{{/if}}
An embed_url can supply an iframe for a theme-owned dialog. The provider handles subscriptions; ZeroPress does not inject provider scripts. Build Pages has no site.newsletter config field, so Markdown sites can use custom HTML or theme-specific markup for this integration.
External Scripts
Put reusable theme behavior in a partial that loads an asset such as /assets/theme.js. For site-specific analytics or verification, use Preview Data’s trusted custom_html slots. This is a Preview Data fragment:
{
"custom_html": {
"head_end": "<meta name=\"site-verification\" content=\"example-value\">",
"body_end": "<script defer src=\"/vendor/site.js\"></script>"
}
}
Place site.js in public/vendor/ for that example. Slots insert the strings without sanitizing them or rewriting asset URLs. Include closing </head> and </body> tags in the layout so configured slots have an insertion point. For Markdown sites, use the Build Pages configuration.