The Cloudinary Plugin is for Grav CMS. Cloudinary is an asset management and delivery service for images and videos, providing on the fly transformation and many other useful options. This plugin currently lets you build listing pages of videos with linked thumbnails and single pages that display the actual video. See below for future plans.
You need a Cloudinary account to use this plugin! There is a free tier with generous limitations available.
Many, many thanks go to the folks at Cloudinary for offering such easily integratable APIs and widgets and things, but also to Team Grav for making Admin integration mostly a matter of properly-formatted yaml files in the right places. I would also like to shout out to quite a few other plugin writers whose plugins I used to learn from, and especially to the ones whose code I shamelessly copied in places: Simon Cramer (srcset-helper plugin) and Aaron Dalton (blogroll plugin, among others). Check out their stuff, it's good!
Installing the Cloudinary plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
GPM Installation (Preferred)
The simplest way to install this plugin is via the Grav Package Manager (GPM) through your system's terminal (also called the command line). From the root of your Grav install type:
bin/gpm install cloudinary
This will install the Cloudinary plugin into your
/user/plugins directory within Grav. Its files can be found under
To install this plugin, just download the zip version of this repository and unzip it under
/your/site/grav/user/plugins. Then, rename the folder to
cloudinary. You can find these files on GitHub or via GetGrav.org.
You should now have all the plugin files under
If you use the admin plugin, you can install directly through the admin plugin by browsing the
Plugins tab and clicking on the
Before configuring this plugin, you should copy the
user/config/plugins/cloudinary.yaml and only edit that copy.
You also need to:
- get a Cloudinary account
- configure an unsigned preset, OR upload your files directly in Cloudinary
- if you're planning to show videos > 40 MB you MUST configure eager transformations in the preset you are using to upload the files, and set eager async to enabled!
- make sure none of your files are larger than 100 MB
Here is the default configuration and an explanation of available options:
enabled: true cloud_name: your_cloud_name key: your_key secret: your_secret unsigned_preset: unsigned_preset defaults_gallery: options: fetch_format: auto quality: 70 maxWidth: 600 minWidth: 200 stepSize: 200 defaultImageSize: 100vw size: - screenSize: (min-width:36em) imageSize: 50vw - screenSize: (min-width:45em) imageSize: 33vw defaults_video: options: width: 900 controls: true fetch_format: auto defaults_image: options: width: 1280 fetch_format: auto
These are just example settings. Your cloud name, key and secret are required to find actual files to display. If you wish to use the embedded upload widget, you need to define a preset for unsigned uploads in Cloudinary and enter that preset's name in the plugin configuration. You can set default options for your gallery pages as well as for single pages with videos or images, Cloudinary has an extensive list of available options for videos as well as options for images. Just list them under the appropriate heading, with proper indentation (or use Grav Admin).
Note that if you use the Admin plugin, a file with your configuration, and named cloudinary.yaml will be saved in the
user/config/plugins/ folder once the configuration is saved in the admin. Saving a page with a cloudinary template will also automagically add these default options to that page.
If you need to make any changes in the templates, copy the ones you wish to change from
user/plugins/cloudinary/templates to the
templates folder of your preferred theme, and adapt them as needed.
To add a new page that displays a thumbnail gallery of either videos or images that are linked to a page with the original file and optional text:
- Add a page with the
resource_type: imagein that page's header, depending on what you want displayed on that page, along with the options you want (Grav Admin will give you some defaults to start with!).
- Add child pages to the gallery page that use either the
- Set the child pages'
headerentries like this (again, Grav Admin will give you some default options):
title: 'Title of your video/image' public_id: cloudinary_public_id options: width: 900 controls: true
You can find and change an asset's public id in the media library of your Cloudinary account.
Admin upload options
If you're using the Admin plugin, you can either upload your files to Cloudinary separately and just copy and paste the public id of the file you want in the appropriate field of the Cloudinary tab when creating or editing a page with the
If you want to change the text that will appear in the alt tag of the thumbnails on listing pages, copy the language contents of
user/plugins/cloudinary/languages.yaml that you wish to change (
user/languages/en.yaml or another language file respectively, and change that so your custom text will not get overridden when the plugin is updated.
At the moment you need to
upload and manage files directly in your Cloudinary account, and you need to add a child page for each single file. If you wish to stay within the limits of the free plan, I suggest you regularly check your Cloudinary account and prune any files you do not need any more. I have some ideas for :
- add format options fields to Admin
- add management options, especially uploading, via Grav Admin plugin
- add support for images
- write up a detailed howto for working with large video files
- add support for image galleries with all images attached directly to a page
- add option for featherlight galleries for images
- add support for Markdown shortcodes
- test whether the plugin clashes with responsive image plugins or the like
- add support for subfolders in Cloudinary
Let me know if you have suggestions for improvement!