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.

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.

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.