Masthead Documentation

Creating a custom theme

An introduction to building Masthead themes, including the development workflow, theme structure and core concepts.

Themes are the foundation of every Masthead site. A theme defines both how a website looks and how it is managed. Besides templates and styling, a theme also controls the editing experience by exposing theme tokens and page metadata.

This guide walks through creating your first theme and introduces the files that make up a Masthead theme. Individual concepts are covered in more detail throughout the rest of the documentation.

Creating a theme

The easiest way to get started is by using the Masthead CLI.

masthead new my-theme

This creates a new theme from the official starter template. The generated theme already contains a complete, working website together with example configuration and preview content.

Change into the newly created directory and start the preview server.

cd my-theme
masthead preview

The theme is now available locally at http://localhost:4010.

Theme structure

Every Masthead theme follows the same directory structure.

manifest.json
theme.css
templates/
  layout.liquid
  index.liquid
  page.liquid
  post.liquid
  not_found.liquid
  pages/
assets/
preview.json

Not every file is required immediately, but every theme starts from the same structure.

The development workflow

Developing a Masthead theme is an iterative process.

  1. Create a theme using the CLI.
  2. Start the preview server.
  3. Edit templates, styles and configuration.
  4. Preview the result instantly.
  5. Package the theme.
  6. Upload it to Masthead.

The local preview reproduces the same rendering pipeline as the hosted platform, allowing you to develop themes without repeatedly uploading them.

Understanding the theme

A Masthead theme consists of four different parts.

Templates

Templates define the HTML structure of your website using the Liquid template language.

They determine how pages, posts and other content are rendered.

Styling

All styling lives inside theme.css.

Besides regular CSS, theme tokens automatically become CSS custom properties, making it easy to create configurable themes without writing additional JavaScript.

Configuration

A theme exposes configuration through two mechanisms.

Theme tokens define site-wide settings such as colours, navigation or typography.

Page metadata defines settings for individual pages, allowing each page template to expose exactly the options it requires.

Together these determine the editing experience shown inside Masthead.

Assets

Images, fonts and other static files belong inside the assets directory.

These files are automatically included when packaging the theme and can be referenced from Liquid templates.

Previewing your changes

While the preview server is running, changes are reflected automatically.

Updating a Liquid template, modifying theme.css or changing the theme manifest immediately refreshes the preview.

The editor also allows you to modify theme tokens and page metadata without editing JSON files manually, making it easy to experiment while developing.

Packaging

Once your theme is ready, package it into an installable archive.

masthead package

The CLI validates the theme before packaging it and produces the same archive format accepted by Masthead.

The resulting ZIP file can be uploaded through the Masthead theme marketplace or installed on a self-hosted instance.

Next steps

This guide introduced the overall structure of a Masthead theme.

The following guides explain each part in more detail:

  • Manifest
  • Templates
  • Theme pages
  • Theme tokens
  • Page metadata
  • Lists and objects
  • Preview content
  • Packaging