Preview content

The Masthead CLI can preview a theme without connecting to a Masthead instance.

To make this possible, the CLI loads preview content from your theme directory. This allows you to develop against realistic pages, posts and site settings while keeping the theme completely self-contained.

The preview file

Preview data is defined in a preview.json file at the root of your theme.

preview.json

The file describes the site that should be rendered by the preview server.

A typical preview file contains:

• Site information
• Theme token values
• Pages
• Posts
• Uploads

{
  "site": {
    "title": "Acme",
    "description": "Example website"
  },
  "pages": [],
  "posts": []
}

When no preview file exists, Masthead generates example content automatically so you can start developing immediately.

Site information

The site object defines the site rendered by the preview server.

Typical values include:

• Name
• Title
• Description
• Slug
• Homepage

These values are exposed through the site object inside Liquid.

Preview pages

Pages can be defined directly inside preview.json.

{
  "pages": [
    {
      "title": "About",
      "slug": "about",
      "format": "markdown"
    }
  ]
}

For larger themes it is often more convenient to store pages as individual Markdown files.

preview/
  pages/
    about.md
    contact.md

This keeps preview content organized and makes longer pages easier to edit.

Preview posts

Posts can also be declared inside preview.json.

{
  "posts": [
    {
      "title": "Hello world",
      "slug": "hello-world"
    }
  ]
}

Or as individual Markdown files.

preview/
  posts/
    first-post.md
    second-post.md

Markdown files support frontmatter, allowing titles, tags, publication dates and metadata to be declared alongside the content.

Theme tokens

Preview files can provide values for every theme token.

{
  "tokens": {
    "accent": "#2563eb",
    "logo": "/uploads/logo.svg"
  }
}

This makes it possible to preview different configurations without modifying the theme itself.

Local overrides

The preview editor stores local changes in:

preview.local.json

This file overrides values from preview.json but is never packaged with the theme.

It is intended for temporary development changes and is automatically ignored by Git.

Development workflow

A typical development workflow looks like this:

1. Start the preview server.
2. Edit templates or styles.
3. Adjust preview content when needed.
4. Refresh the browser.

Because preview content lives alongside the theme, every developer working on the theme starts from the same example website.

Next steps

Once your theme is complete, it can be validated and packaged into a distributable archive.

The final guide explains how to package a theme for installation or publication.