Theme Manifest Reference

This reference documents every option available in the outpost-manifest.yaml file. For a quick introduction, see Getting Started.

File Location

The manifest file must be named outpost-manifest.yaml and placed in your theme’s root directory, alongside package.json.

your-theme/
├── package.json
├── outpost-manifest.yaml  ← here
├── default.hbs
├── post.hbs
└── ...

Schema Overview

manifest_version: 1           # Required: must be 1

events:                       # Optional: include for event-capable themes
  default_tags: []            # Optional: tags for all event types
  types:                      # Required within events: at least one type
    type_key:                 # Your type identifier (e.g., "webinar")
      label: "Display Name"
      post_template: "custom-template"  # Required
      tags: []
      supported_fields: []
      required_fields: []
      field_constraints: {}
      custom_fields: []
      messaging_states: []
      default: true           # Optional: preselect this type in the event editor

Top-Level Fields

manifest_version

Required. Must be 1. This enables future schema evolution without breaking existing manifests.

manifest_version: 1

events

Optional. Contains all event-related configuration. Include it when your theme supports Outpost events; a manifest can declare events, homepage_curation, or both.

Events Section

events.default_tags

Optional. Array of Ghost tag names applied to ALL event types when published.

events:
  default_tags:
    - "event"
    - "registration-open"

Tags are strings. Invalid entries (non-strings) are silently ignored.

events.types

Required when events is present. Object where each key is an event type identifier and the value is that type’s configuration.

events:
  types:
    webinar:
      # ... webinar config
    workshop:
      # ... workshop config
    meetup:
      # ... meetup config

Type keys should be lowercase with underscores (e.g., in_person, virtual_workshop). These keys are stored on event records and used for identification.

Event Type Configuration

Each event type supports the following fields:

post_template

Required. The Ghost custom template filename (without .hbs extension) used for this event type’s posts.

types:
  webinar:
    post_template: "custom-webinar"

This template must exist in your theme. Events using this type will have their Ghost posts set to use this template.

label

Optional. Human-readable name shown in the Outpost UI. Defaults to the type key with underscores replaced by spaces and the first letter capitalized.

types:
  in_person:
    label: "In-Person Event"  # Shows as "In-Person Event" in dropdown

supported_fields

Optional. Array of standard field keys to show for this event type. If omitted, all standard fields are shown.

types:
  webinar:
    supported_fields:
      - name
      - description
      - event_date
      - event_time_start
      - event_time_end
      - event_time_zone
      - platform_url
      - access

See Standard Field Keys for all available fields.

required_fields

Optional. Array of field keys that must be filled before publishing. Must be a subset of supported_fields (or standard fields if supported_fields is omitted).

types:
  webinar:
    required_fields:
      - name
      - event_date
      - platform_url

If a required field is not in supported_fields, it will be ignored with a warning.

field_constraints

Optional. Object holding constraint hints for standard fields. Outpost surfaces feature_image constraints as recommended image dimensions in the event editor; constraints on other standard fields are stored with the manifest but are not enforced when publishing.

types:
  in_person:
    field_constraints:
      feature_image:
        aspect_ratio: "16:9"
        min_width: 1200
        min_height: 630
      description:
        max_length: 500

A feature_image constraint reaches the publisher as a comma-joined phrase built from min_width (“1200px wide”), min_height (“630px tall”), and aspect_ratio (“16:9 aspect ratio”). The phrase shows under the Featured Image field and again inside the Crop Image dialog. Only aspect_ratio shapes the crop stencil. min_width and min_height set the smallest image the editor will produce: a crop smaller than those values is scaled up to meet them after the crop is applied. If an event type sets no feature_image constraint, the editor falls back to the site’s Event Settings, under Default Featured Image Size. If neither is set, it shows a built-in recommendation of 1200 x 630px, so publishers always see a recommended size. See Field Constraints for available constraint options.

custom_fields

Optional. Array of custom field definitions for theme-specific data.

types:
  webinar:
    custom_fields:
      - key: speaker_name
        label: "Speaker Name"
        type: text
        required: true

See Custom Field Types for complete options.

messaging_states

Optional. Array of messaging state names. Outpost validates the names in this key but does not act on it. Event Settings offers all seven messaging states no matter what an event type declares here.

types:
  webinar:
    messaging_states:
      - can_register
      - registered
      - event_passed

A state name Outpost does not recognize produces a finding, and any finding keeps Homepage Curation from activating. Because the key has no effect, leaving it out is the safer choice.

See Messaging States for the names Outpost recognizes.

default

Optional. Boolean. Mark one event type with default: true and Outpost preselects it in the Event Type dropdown when a publisher creates a new event.

types:
  webinar:
    default: true
    post_template: "custom-webinar"

If more than one type claims it, Outpost keeps the first and records a finding for the rest.

Standard Field Keys

These are the built-in fields available for supported_fields and required_fields:

Key	Description	Data Type
`name`	Event name/title	string
`slug`	URL-safe identifier	string
`description`	Event description (used as post excerpt)	string
`event_date`	Date of the event	date
`event_time_start`	Start time	string (e.g., “10:00 am”)
`event_time_end`	End time	string (e.g., “11:00 am”)
`event_time_zone`	IANA timezone	string (e.g., “America/New_York”)
`location`	Venue or location text	string
`platform_url`	Virtual event platform link	URL string
`max_attendees`	Capacity limit	integer
`feature_image`	Featured/hero image	URL string
`access`	Who can register	enum: `anyone`, `free`, `paid`
`rsvp_labels`	Labels applied to registrants	array of strings
`registration_deadline`	Registration cutoff date	date
`deadline_time_end`	Registration cutoff time	string

Field Constraints

Available constraints vary by field type:

Constraints on standard fields are guidance for editors, not publish-time validation. Outpost currently reads feature_image constraints to show recommended image dimensions in the event editor; the rest are stored with the manifest for future use. With no feature_image constraint, the editor falls back to the site’s Event Settings, under Default Featured Image Size, and then to a built-in 1200 x 630px recommendation.

Text/Textarea Fields

field_constraints:
  description:
    max_length: 500        # Maximum character count
    pattern: "^[A-Z]"      # Regex pattern (optional)

Image Fields

field_constraints:
  feature_image:
    aspect_ratio: "16:9"   # Width:height ratio
    min_width: 1200        # Minimum width in pixels
    min_height: 630        # Minimum height in pixels

min_width and min_height set the smallest crop the editor will produce: a smaller selection is scaled up to meet them.

Number Fields

field_constraints:
  max_attendees:
    min: 1
    max: 1000

Custom Field Types

Custom fields support these types:

text

Single-line text input.

- key: speaker_name
  label: "Speaker Name"
  type: text
  required: true
  help_text: "Full name of the presenter"
  max_length: 100
  pattern: "^[A-Za-z\\s]+$"

textarea

Multi-line text input.

- key: speaker_bio
  label: "Speaker Bio"
  type: textarea
  required: false
  max_length: 500

number

Numeric input with optional range constraints.

- key: session_duration
  label: "Duration (minutes)"
  type: number
  required: true
  min: 15
  max: 480

select

Dropdown with predefined options.

- key: session_type
  label: "Session Type"
  type: select
  required: true
  options:
    - Keynote
    - Breakout
    - Workshop
    - Panel

Select fields must include an options array. Fields without options are skipped with an error.

url

URL input with validation.

- key: slides_url
  label: "Slides URL"
  type: url
  required: false
  help_text: "Link to presentation slides"

date

Date picker input.

- key: early_bird_deadline
  label: "Early Bird Deadline"
  type: date
  required: false

toggle

Boolean switch input.

- key: is_recorded
  label: "Will Be Recorded"
  type: toggle
  required: false

image

Image upload with optional constraints.

- key: speaker_photo
  label: "Speaker Photo"
  type: image
  required: false
  aspect_ratio: "1:1"
  min_width: 400
  max_file_size_kb: 2048

Custom Field Properties

All custom field types support these properties:

Property	Type	Required	Description
`key`	string	Yes	Unique identifier (no spaces, lowercase recommended)
`label`	string	No	Display label (defaults to formatted key)
`type`	string	Yes	One of the field types above
`required`	boolean	No	Whether field must be filled (default: false)
`help_text`	string	No	Helper text shown below the field

Custom field keys must not collide with standard field keys. Keys like name, event_date, access, etc. will be rejected with an error.

At publish time, Outpost enforces required, number min/max, URL format, select options, and max_length on text and textarea fields. Other values (pattern, and image aspect_ratio, min_width, max_file_size_kb) are stored with the field but not yet enforced.

Messaging States

These are the messaging state names Outpost recognizes:

State	When Shown to Members
`can_register`	Eligible member who hasn’t registered
`login_required_free`	Guest on a free event
`login_required_paid`	Guest on a paid event
`upgrade_required`	Free member on a paid event
`registered`	Member who has RSVP’d
`registration_closed`	After registration deadline
`event_passed`	After the event ends

All seven are editable in Event Settings, a site-wide screen. See messaging_states for what an event type’s key does.

Homepage Curation Section

Optional. Declares curated homepage regions that a publisher can fill from the Outpost UI. When a theme’s manifest includes a top-level homepage_curation key, Outpost shows a Homepage Curation screen (under Posts) where editors pick which post occupies each slot, without hand-editing tags in Ghost. homepage_curation and events are independent top-level keys in the same outpost-manifest.yaml; a theme can declare either, both, or neither.

homepage_curation:
  sections:                              # Required: one or more sections
    - key: featured-us                   # Section identifier (unique)
      name: "Featured (US)"              # Display name in the curation UI
      description: "Top-of-homepage hero carousel."   # Optional helper text
      picker:                            # Optional: controls the post picker
        default_view: recent             # Default tab: recent or search, nothing else
        recent_limit: 30                 # Recent posts to offer: default 20, maximum 50
        recent_filter:                   # Optional: pre-scope picker to a tag
          tag: local-news
      slots:                             # Required: one or more slots
        - { key: slot-1, label: "Slot 1", tag: hash-home-hero-slot-1 }
        - { key: slot-2, label: "Slot 2", tag: hash-home-hero-slot-2 }

How slots work

Each slot binds one Ghost tag to one post. The theme renders whichever single post currently carries that tag; the curation UI swaps which post wears it. Slot tags are ordinary Ghost internal tags: a hash- prefix maps to a # internal tag.

Field	Required	Description
`sections[].key`	Yes	Unique identifier for the section
`sections[].name`	Yes	Display name shown in the curation UI
`sections[].description`	No	Helper text shown under the section
`sections[].picker.default_view`	No	Default picker tab. Exactly `recent` or `search`, defaulting to `recent`
`sections[].picker.recent_limit`	No	How many recent posts to list. A positive whole number, defaulting to 20 and capped at 50
`sections[].picker.recent_filter.tag`	No	Restrict the picker to posts carrying this tag
`slots[].key`	Yes	Unique identifier for the slot within its section
`slots[].label`	Yes	Label shown above the slot in the UI
`slots[].tag`	Yes	Ghost tag that binds a post to this slot

Be exact with these two values. Both are corrected for you rather than rejected, but each records a finding, and any finding keeps Homepage Curation from activating. default_view accepts only recent and search; any other value is replaced with recent. recent_limit falls back to 20 when it is not a positive whole number. A value above 50 is reduced to 50, with no finding.

Homepage Curation is an early Labs-status feature, found under Posts in the left menu, and currently ships in the single-file manifest format. A complete worked example is bundled with the docs as cascade-homepage-curation.yaml.

Error Handling

Outpost validates the manifest every time a theme is uploaded or the manifest is refreshed. Each problem it finds is recorded alongside the manifest data as a finding, carrying a field path, a message, and a severity of either error or warning.

Activation requires a clean manifest

Homepage Curation only activates from a manifest that validated with zero findings, warnings included. One warning anywhere in the file is enough to stop the whole manifest from activating, even when it sits on a section unrelated to the curation slots you are adding.

Severity changes how a finding is worded, not what happens to your manifest. A finding marked warning blocks Homepage Curation exactly as a finding marked error does. Treat the findings list as a to-do list that must reach empty, not as a set of suggestions.

The practical consequence for a manifest that has never validated cleanly: the Homepage Curation screen never appears under Posts. There is no partially-activated state to look for. If the menu is missing, open the findings list and clear every entry in it, whatever the severity says. Once a manifest has activated, Outpost keeps that copy as the last known-good version. A later push that fails validation does not take a live feature offline: Homepage Curation keeps running on the last version that validated cleanly, and your new changes do not appear until the findings are cleared. This is the only sense in which anything is “kept” across a failed push. The same protection covers a refresh that cannot complete. If Outpost cannot reach GitHub, or the token it uses is rejected, or the request fails for any other reason, it reports the failure and leaves both the stored manifest and the last known-good copy exactly as they were.

There is one exception. If the refresh finds no outpost-manifest.yaml in the repository, Outpost treats the file as deliberately removed and clears the stored manifest along with the last known-good copy. Homepage Curation then switches off. Deleting or renaming the manifest file and refreshing is the one action that takes the feature offline. Restoring the file and refreshing again brings it back.

Event types behave differently. The event editor reads the most recent manifest directly, so it does drop the parts that failed validation and keep the parts that passed. An unknown field name in one event type does not hide your other event types. Homepage Curation is the feature with the all-or-nothing activation rule.

Error Categories

Every category below blocks Homepage Curation activation. The severity column is the label Outpost puts on the finding, and the effect column describes what validation does to that part of the manifest before storing it.

Category	Reported as	Effect on the stored manifest
YAML syntax error	Error	Nothing is stored, manifest ignored entirely
Unknown manifest_version	Warning	Nothing is stored, manifest ignored entirely
Missing or invalid `types` section	Warning	No event types are stored
Missing post_template	Error	Event type dropped
Multiple event types marked as default	Warning	The first type stays default, the rest lose the key
Unknown standard field	Warning	Field key dropped
Required field not in supported	Warning	Requirement dropped
Unknown messaging state	Warning	State name dropped
A list key given a non-list value	Warning	Key ignored
Custom field missing `key`	Error	Custom field dropped
Custom field missing `type`	Error	Custom field dropped
Custom field key collision	Error	Custom field dropped
Unknown custom field type	Error	Custom field dropped
Missing options on select	Error	Custom field dropped
Missing or invalid `sections` array	Warning	Whole `homepage_curation` section dropped
Missing or duplicate section key	Error	Curation section dropped
Missing section name	Error	Curation section dropped
Section with no valid slots	Error	Curation section dropped
Missing or duplicate slot key	Error	Slot dropped
Missing slot label	Error	Slot dropped
Missing or duplicate slot tag	Error	Slot dropped
Invalid picker `default_view` or `recent_limit`	Warning	Value replaced with the default
Invalid picker `recent_filter.tag`	Warning	Filter dropped
Unknown picker key	Warning	Key dropped

The list keys are default_tags, tags, supported_fields, required_fields, custom_fields, and messaging_states. Two rows show why severity is not a guide to consequences. An unknown manifest_version is labelled a warning and discards the entire manifest. An unknown picker key is labelled a warning, has no effect on the stored manifest at all, and still keeps Homepage Curation from activating.

Viewing Errors

Findings are visible in:

The Manifest Status column of the Themes table, in Labs → Theme Connect Wizard. Click the info icon next to the count to list them.
The event editor, as a banner at the top of the form.
The theme upload or refresh API response.

The Manifest Status column is the check to run before anything else. It reads Valid only when the manifest produced zero findings, which is also the only state in which Homepage Curation activates. Anything else reads as a count of warnings, and that count includes both severities: 3 warning(s) can mean three errors. Aim for Valid, not for a low count.

Example Error Response

{
  "_errors": [
    {
      "field": "types.webinar.post_template",
      "message": "Missing required 'post_template'",
      "severity": "error"
    },
    {
      "field": "types.in_person.supported_fields",
      "message": "Unknown standard field 'title'",
      "severity": "warning"
    }
  ]
}

Complete Example

manifest_version: 1

events:
  default_tags:
    - "event"

  types:
    webinar:
      default: true
      label: "Webinar"
      post_template: "custom-webinar"
      tags:
        - "webinar"
        - "online"

      supported_fields:
        - name
        - description
        - event_date
        - event_time_start
        - event_time_end
        - event_time_zone
        - platform_url
        - feature_image
        - access
        - registration_deadline
        - deadline_time_end

      required_fields:
        - name
        - event_date
        - platform_url

      field_constraints:
        feature_image:
          aspect_ratio: "16:9"
          min_width: 1200
        description:
          max_length: 300

      custom_fields:
        - key: speaker_name
          label: "Speaker Name"
          type: text
          required: true
          help_text: "Full name of the presenter"

        - key: speaker_bio
          label: "Speaker Bio"
          type: textarea
          required: false
          max_length: 500

        - key: session_type
          label: "Session Type"
          type: select
          required: true
          options:
            - Live Presentation
            - Q&A Session
            - Workshop

        - key: is_recorded
          label: "Will Be Recorded"
          type: toggle

    in_person:
      label: "In-Person Event"
      post_template: "custom-in-person"
      tags:
        - "in-person"
        - "conference"

      supported_fields:
        - name
        - description
        - event_date
        - event_time_start
        - event_time_end
        - event_time_zone
        - location
        - max_attendees
        - feature_image
        - access

      required_fields:
        - name
        - event_date
        - location
        - feature_image

      custom_fields:
        - key: venue_address
          label: "Venue Address"
          type: textarea
          required: true

        - key: track
          label: "Track"
          type: select
          required: true
          options:
            - Main Stage
            - Workshop Room A
            - Workshop Room B
            - Networking Hall

​File Location

​Schema Overview

​Top-Level Fields

​manifest_version

​events

​Events Section

​events.default_tags

​events.types

​Event Type Configuration

​post_template

​label

​tags

​supported_fields

​required_fields

​field_constraints

​custom_fields

​messaging_states

​default

​Standard Field Keys

​Field Constraints

​Text/Textarea Fields

​Image Fields

​Number Fields

​Custom Field Types

​text

​textarea

​number

​select

​url

​date

​toggle

​image

​Custom Field Properties

​Messaging States

​Homepage Curation Section

​How slots work

​Error Handling

​Activation requires a clean manifest

​Error Categories

​Viewing Errors

​Example Error Response

​Complete Example

File Location

Schema Overview

Top-Level Fields

manifest_version

events

Events Section

events.default_tags

events.types

Event Type Configuration

post_template

label

tags

supported_fields

required_fields

field_constraints

custom_fields

messaging_states

default

Standard Field Keys

Field Constraints

Text/Textarea Fields

Image Fields

Number Fields

Custom Field Types

text

textarea

number

select

url

date

toggle

image

Custom Field Properties

Messaging States

Homepage Curation Section

How slots work

Error Handling

Activation requires a clean manifest

Error Categories

Viewing Errors

Example Error Response

Complete Example