Gantry 5 on Grav: Framework, Themes and Safe Customisation

Gantry 5 and Grav are different parts of a website. Grav is the content management system; Gantry 5 is a theming framework that can run on Grav; and a theme such as Helium or Hydrogen is the design layer that uses the framework. Keeping those layers separate makes installation and troubleshooting much easier.

This guide explains the relationship, the installation routes documented by Gantry, where custom files belong on Grav, and how to update the framework or a Gantry theme. It is a general technical guide, not a substitute for checking the current requirements and package versions on the official sites. Sources are listed at the end.

How the three pieces fit together

Grav describes itself as a flat-file CMS: content is stored in files rather than a traditional database. Its current homepage also describes Grav as using Markdown and YAML. Gantry's own documentation describes Gantry 5 as a framework that works with Joomla, WordPress and Grav, and identifies its layout system, particles and administrator as framework features.

The framework and theme are separate packages. The Gantry installation guide says that Gantry itself contains the framework pieces, while a theme contains the template. It also says the Gantry 5 framework should be installed before a Gantry-powered theme.

On Grav, the framework is a plugin under user/plugins/gantry5. The theme is under user/themes; for example, the documentation's Helium installation creates user/themes/g5_helium. The theme uses the framework's administrator, layout tools, particles and Twig templates, while its own files supply the theme-specific styles and layouts.

That distinction helps explain common errors. Installing a theme without the framework does not give Grav the underlying Gantry files it expects. Installing the framework without a theme gives you the engine but not a finished visual design.

Requirements to check first

The official requirements page recommends the latest stable Grav release. It also says the Grav Admin plugin is needed if you want to access the Gantry 5 administrator. The page recommends the Login, Form and Email plugins alongside Admin for a manageable Grav installation, while noting that Grav can technically run without Admin.

Current packages can impose newer requirements than older documentation. For example, the current Gantry downloads page lists Grav 1.7.25+ for its 5.6.4 Grav packages. The Helium theme's current Grav blueprint in the public source repository declares dependencies on Grav >=1.7 and Gantry 5 >=5.5. Treat those as release-specific checks, not permanent rules.

Before installing, record your Grav version, confirm the Gantry package is intended for it, and take a backup of the site files. Grav is file-based, but that does not make changes risk-free: the site content, configuration, theme and plugins still need to be recoverable.

Installing the Gantry 5 framework

The Gantry installation guide documents four ways to install the framework on Grav.

1. Grav Admin

With the Admin plugin installed and active, open Admin, Plugins and select Add. Find Gantry 5 Framework, select Install and confirm Continue in the dialog.

2. Tools panel

The Tools panel can install a zip package uploaded from your computer, or a package supplied by a direct remote URL. This route is useful when the package is not being installed through the normal repository flow, but verify the URL and archive before using it.

3. File management

Download the current framework package from Gantry.org and unpack it in user/plugins. The documentation says this creates a gantry5 directory and should make the plugin available automatically.

4. Grav Package Manager

From the root directory of the Grav site, run:

bin/gpm install gantry5

Confirm the installation when prompted. The GPM route is convenient for an administrator who already works on the server through a terminal.

Installing a Gantry theme

After the framework is in place, choose a Gantry-powered theme. The documentation uses Helium as its Grav example. Themes listed in the Grav repository can be installed with Admin, by placing a zip in user/themes, or with GPM:

bin/gpm install helium

The theme's directory name is g5_helium. To activate it through the Admin, open Admin, Themes, select the theme and choose Activate. You can also set it in user/config/system.yaml:

pages:
  theme: g5_helium

Do not assume that a theme name, package name and directory name are identical for every theme. Check the theme's own documentation or the installed directory before changing configuration.

Where custom files belong

The most important Grav-specific rule is that Gantry's custom data does not use the same custom folder path as Joomla or WordPress. For a theme called THEME_DIR, the documented Grav custom location is:

user/data/gantry5/themes/THEME_DIR/

For the Helium example that becomes user/data/gantry5/themes/g5_helium/. Custom particles go in its particles directory, and custom layout, style or engine files follow the same directory structure as their originals. For example, custom style presets belong in:

user/data/gantry5/themes/THEME_DIR/gantry/presets.yaml

The file-overrides guide explicitly says not to add a /custom/ folder in the Grav case. That differs from Joomla's TEMPLATE_DIR/custom/ and WordPress's THEME_DIR/custom/ paths.

Gantry's moving-settings tutorial explains why this works: custom settings, layouts and custom CSS are stored as flat files, so they can be backed up and moved between instances. Moving them between themes or platforms may still require reconfiguration if one theme lacks a particle or uses different outline IDs.

Customising particles and templates

A particle is a configurable block. A custom particle normally has a YAML blueprint and a matching Twig template. The YAML declares the fields shown in the administrator; the Twig file renders the values. Grav's custom particle path is:

user/data/gantry5/themes/THEME_DIR/particles

For a theme file override, reproduce the relevant directory path under the same custom theme data root. Gantry's documentation says that keeping these copies in the custom location prevents the original theme or framework update from replacing them. If an override causes a problem, deleting the contents of the custom directory should return the theme to its out-of-the-box defaults, provided the change was made there rather than directly in the original files.

Use care with engine overrides. Gantry identifies the Nucleus engine as core layout code and labels customising these files an advanced action. Start with a theme-level custom file or particle where possible, keep a backup and make one change at a time.

Updating on Grav

The update guide gives several routes for Gantry themes and plugins.

• Individual theme or plugin update: in Grav Admin, an update notice appears on the theme or plugin. Open its details and use the update control.
• Dashboard: the Maintenance area can update all plugins and themes together.
• Command line: bin/gpm update updates all installed plugins and themes; bin/gpm update helium updates only the Helium theme. The framework equivalent is bin/gpm update gantry5.
• Tools or file manager: for packages not listed in GPM, upload a zip through Tools or replace the backed-up directory manually. The framework documentation marks the file-manager route as not recommended when customisations or compatibility issues could disrupt the site.

Back up user/themes, user/plugins, user/data and configuration before updating. Afterward, check the front end, the Admin, assigned outlines and any custom particles. A custom file may survive while an underlying setting or particle changes between versions.

A practical troubleshooting order

If a Gantry theme does not appear or renders an error, work from the layers outward:

1. Confirm the theme directory exists under user/themes and that its name matches the configured theme.
2. Confirm the Gantry 5 plugin is installed under user/plugins/gantry5 and available in Grav.
3. Check that the Admin plugin is installed if you expect Gantry's administrator.
4. Review the package requirements for the installed Grav and Gantry versions.
5. Temporarily inspect the custom data under user/data/gantry5/themes/THEME_DIR. A broken override can be isolated by backing it up and removing it, not by editing the original theme files.
6. Recheck the theme's outline and particle configuration after an update.

This order separates installation problems from theme configuration problems and protects the files that should survive updates.

Sources

• Grav homepage (CMS description and current release information): https://getgrav.org/
• Gantry 5 documentation, Introduction: https://docs.gantry.org/gantry5/basics/introduction
• Gantry 5 documentation, Key Features: https://docs.gantry.org/gantry5/basics/key-features
• Gantry 5 documentation, System Requirements: https://docs.gantry.org/gantry5/basics/system-requirements
• Gantry 5 documentation, Installation: https://docs.gantry.org/gantry5/basics/installation
• Gantry 5 documentation, Creating Custom File Overrides: https://docs.gantry.org/gantry5/advanced/file-overrides
• Gantry 5 documentation, Updating: https://docs.gantry.org/gantry5/basics/updating
• Gantry 5 documentation, Updating Themes: https://docs.gantry.org/gantry5/basics/updating-themes
• Gantry 5 documentation, Moving Custom Settings Between Themes: https://docs.gantry.org/gantry5/tutorials/moving-between-themes
• Gantry downloads (current package requirements): https://gantry.org/downloads
• Gantry 5 source, Helium Grav blueprint: https://raw.githubusercontent.com/gantry/gantry5/develop/themes/helium/grav/blueprints.yaml