Gantry 5 YAML: How Particle Blueprints, Layout Presets and Style Presets Are Written

Much of what you see in the Gantry 5 administrator is defined in plain text files. The framework's key features page lists "YAML-driven configuration" as one of its pillars and explains that YAML, a human-readable data format, makes it easy to create blueprints for back-end configuration options. Twig handles the markup side.

This guide is for developers who want to read or write those files. It covers the YAML that defines a particle, the field types available to it, the files that make up layout presets and style presets, and where to save your own versions. All examples and paths come from the official Gantry 5 documentation linked at the end.

A short YAML refresher

YAML represents data with very little punctuation. The YAML specification describes how indentation can carry structure, colons separate keys from values, and dashes create list items. In Gantry files that means the indentation is not cosmetic: a field nested one level too shallow ends up in the wrong part of the structure. Use spaces consistently and copy an existing file as your starting point when you can.

Where YAML lives in a Gantry theme

The documentation's guide to customising theme files describes the folders inside a Gantry-powered theme. Several of them are mostly YAML:

blueprints/styles holds YAML files that define the fields and settings shown in the Styles admin panel.
gantry contains presets.yaml, which holds the preset style settings, and theme.yaml, which sets up the About panel.
layouts contains the YAML files for the layout presets offered in the Layout Manager.
particles contains particles, each made of a YAML file and a Twig file.

The Nucleus engine, which the documentation calls the core of Gantry 5's layout system, has its own admin/blueprints folder too. Overriding those engine files is possible but is an advanced step.

Particle YAML: the blueprint

A custom particle needs two files with the same base name: a YAML file that acts as the blueprint, and a .html.twig file that renders it. The documentation's example blueprint looks like this:

name: Example
description: Displays a Title, Image, and Text on the front end.
type: particle
form:
  fields:
    enabled:
      type: input.checkbox
      label: Enabled
      description: Globally enable to the particles.
      default: true
    title:
      type: input.text
      label: Title
      description: Customize the section title text.
    image:
      type: input.imagepicker
      label: Image
      description: Select the main image.
    description:
      type: textarea.textarea
      label: Text / HTML
      description: Create or modify your description.
    css.class:
      type: input.text
      label: Class
      description: CSS class name for the particle.

The file has two parts.

The head. name is the title shown in the Particle Defaults and Layout Manager panels. type tells Gantry whether the file defines a standard particle, an atom or a position. The documentation notes you will rarely create positions, because a configurable Module Position particle already exists, but an atom would use type: atom.

The form. Each entry under fields becomes an input in the administrator. The enabled field is required: it adds the switch that turns the particle on or off. Every other field is up to you.

The Twig file then reads those values from the particle object, so title above becomes {{ particle.title }} in the markup. The documentation lists three required parts for the Twig file: the line {% extends '@nucleus/partials/particle.html.twig' %}, a {% block particle %} wrapper, and the markup inside it.

Field types you can use

The field type decides what the site manager sees. The documentation groups the types in three families.

Standard HTML inputs. These include input.text, input.checkbox, input.number, input.url, input.email, input.color, input.date, input.range, input.hidden, textarea.textarea and collection.list, among others.

Gantry-specific inputs. These open Gantry's own tools:

input.colorpicker for the colour selector
input.imagepicker, input.filepicker and input.videopicker for the file browser
input.fonts for the font selector, which the documentation says lets you preview more than 670 Google Fonts
input.icon for choosing a Font Awesome icon
input.block-variations for Gantry's block variations
select.selectize and select.date for preset option lists

WordPress-only inputs. wordpress.posts and wordpress.categories let a field pick posts or categories.

A select.selectize field needs an options map. The keys are stored as values and the labels are what the user sees:

target:
  type: select.selectize
  label: Target
  description: Target browser window when item is clicked.
  placeholder: 'Select...'
  default: _blank
  options:
    _parent: Self
    _blank: New Window

The documentation warns that using Selectize many times on one page can slow it down, and suggests select.select when you do not need the search box.

Layout preset YAML

Layout presets are the starting points the Layout Manager loads. Each one is a YAML file that lists sections and what goes in them. The documentation's basic example, saved as THEME_DIR/custom/layouts/example1.yaml, begins:

version: 2
preset:
  image: gantry-admin://images/layouts/default.png
layout:
  /header/:
    -
      - menu
  /main/:
    -
      - position-breadcrumbs
    -
      - system-messages
    -
      - system-content

A few conventions are worth knowing:

preset.image sets the thumbnail shown in the Outlines panel. gantry-admin:// points at images bundled with Gantry; gantry-media:// points at your own images in the custom folder.
Sections are written as /name/:. Each - under a section starts a row, and the nested items are the particles or positions in that row.
Widths can follow an item name. The example footer row copyright 40, spacer 30, branding 30 splits the row by percentage.
Sidebars are defined inside a container section, for example main 60, sidebar1 20 and sidebar2 20 under /container-main/.

If you add a section the theme does not already style, the documentation says it will appear with only the template's default styling. You add your own rules in custom.scss under THEME_DIR/custom/scss, where sections use the g- prefix, such as #g-mainbottom.

Style preset YAML

Style presets live in presets.yaml. Each top-level key, such as preset1, is the preset's tag and should be lowercase with no spaces. Under it, image sets the thumbnail, description is the display name, colors lists the swatches shown under the thumbnail, and styles holds the values grouped by section: base, accent, menustyle, font, header, footer, breakpoints and so on.

Two points from the documentation prevent most surprises:

A custom presets.yaml replaces the theme's file rather than adding to it. Copy the original from THEME_DIR/gantry/ and edit the copy.
The variable names are defined by the theme, not by Gantry core. A new variable does nothing until your own SCSS uses it.

Where to save your YAML

Keep every custom file out of the theme's original folders, or a theme update can overwrite it. The documentation gives these locations:

Joomla: TEMPLATE_DIR/custom/ (for example custom/particles, custom/layouts, custom/gantry)
WordPress: THEME_DIR/custom/
Grav: user/data/gantry5/themes/THEME_DIR/, without an extra /custom/ folder

If an override breaks something, the documentation says deleting the contents of the custom directory should return the theme to its out-of-the-box defaults.

Checklist before you save a file

Start from a copy of a working file and keep its indentation.
Use a file name without special characters such as hyphens, as the particle guide advises.
Keep the enabled field in particle blueprints.
Give layout presets a version and a preset.image.
Style any new section in custom.scss.
Save everything in the custom location for your platform.

Sources

Gantry 5 documentation, Key Features: https://docs.gantry.org/gantry5/basics/key-features
Gantry 5 documentation, Creating a New Particle: https://docs.gantry.org/gantry5/advanced/creating-a-new-particle
Gantry 5 documentation, Particle YAML Field Types: https://docs.gantry.org/gantry5/advanced/particle-yaml-field-types
Gantry 5 documentation, Creating Layout Presets: https://docs.gantry.org/gantry5/advanced/creating-layout-presets
Gantry 5 documentation, Creating Style Presets: https://docs.gantry.org/gantry5/advanced/creating-style-presets
Gantry 5 documentation, Customizing Theme Files: https://docs.gantry.org/gantry5/advanced/customizing-theme-files
Gantry 5 documentation, Creating Custom File Overrides: https://docs.gantry.org/gantry5/advanced/file-overrides
YAML Ain't Markup Language, Version 1.2.2 specification: https://yaml.org/spec/1.2.2/