Cloudinary
Last updated
Last updated
The Cloudinary media library integration for Netlify CMS uses Cloudinary's own media library interface within Netlify CMS. To get started, you'll need a Cloudinary account and Netlify CMS 2.3.0 or greater.
You can sign up for Cloudinary for free. Once you're logged in, you'll need to retrieve your Cloud name and API key from the upper left corner of the Cloudinary console.
To use the Cloudinary media library within Netlify CMS, you'll need to update your Netlify CMS configuration file with the information from your Cloudinary account:
Note: The user must be logged in to the Cloudinary account connected to the api_key
used in your Netlify CMS configuration.
Note: The Netlify CMS media library extensions for Cloudinary are not included in netlify-cms-app
. If you're using netlify-cms-app
, you'll need to register the media libraries yourself.
Although this setup exposes the cloud_name
and api_key
publicly via the /admin/config.yml
endpoint, this information is not sensitive. Any integration of the Cloudinary media library requires this information to be exposed publicly. To use this library or use the restricted Cloudinary API endpoints, the user must have access to the Cloudinary account login details or the api_secret
associated with the cloud_name
and api_key
.
The following options are specific to the Netlify CMS integration for Cloudinary:
output_filename_only
: (default: false
)
By default, the value provided for a selected image is a complete URL for the asset on Cloudinary's CDN. Setting output_filename_only
to true
will instead produce just the filename (e.g. image.jpg
). This should be true
if you will be directly embedding cloudinary transformation urls in page templates. Refer to Inserting Cloudinary URL in page templates.
use_transformations
: (default: true
)
If true
, uses derived url when available (the url will have image transformation segments included). Has no effect if output_filename_only
is set to true
.
use_secure_url
: (default: true
)
Controls whether an http
or https
URL is provided. Has no effect if output_filename_only
is set to true
.
The following options are used to configure the media library. All options are listed in Cloudinary's media library documentation, but only options listed below are available or recommended for the Netlify CMS integration:
cloud_name
api_key
default_transformations
- only the first image transformation is used, be sure to use the SDK Parameter
column transformation names from the transformation reference
max_files
_- has no impact on images inside the _markdown widget. Refer to media library documentation for details on this property
multiple
_- has no impact on images inside the _markdown widget. Refer to media library documentation for details on this property
The Cloudinary integration allows images to be transformed in two ways: directly within Netlify CMS via Cloudinary's Media Library, and separately from the CMS via Cloudinary's dynamic URL's by inserting cloudinary urls.
If you transform and insert images from within the Cloudinary media library, the transformed image URL will be output by default. This gives the editor complete freedom to make changes to the image output. There are two ways to configure image transformation via media library - globally and per field. Global options will be overridden by field options.
Global configuration
Global configuration, which is meant to affect the Cloudinary widget at all times, can be provided as seen below, under the primary media_library
property. Settings applied here will affect every instance of the Cloudinary widget.
Field configuration
Configuration can also be provided for individual fields that use the media library. The structure is very similar to the global configuration, except the settings are added to an individual field
. For example:
If you prefer to provide direction so that images are transformed in a specific way, or dynamically retrieve images based on viewport size, you can do so by providing your own base Cloudinary URL and only storing the asset filenames in your content:
Either globally or for specific fields, configure the Cloudinary extension to only output the asset filename
Provide a dynamic URL in the site template
Your dynamic URL can be formed conditionally to provide any desired transformations - please see Cloudinary's image transformation reference for available transformations.