feat: add cloudinary support (#1932)

This commit is contained in:
Shawn Erquhart
2018-12-04 17:04:52 -05:00
committed by GitHub
parent 9662eb292f
commit 1fc2f50499
15 changed files with 281 additions and 17 deletions

View File

@ -0,0 +1,84 @@
---
title: Cloudinary
group: media
weight: '10'
---
Cloudinary is a digital asset management platform with a broad feature set, including support for responsive image generation and url based image transformation. They also provide a powerful media library UI for managing assets, and tools for organizing your assets into a hierarchy.
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.
## Creating a Cloudinary Account
You can [sign up for Cloudinary](https://cloudinary.com/users/register/free) 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.
![Cloudinary console screenshot](/img/cloudinary-console-details.png)
## Connecting Cloudinary to Netlify CMS
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:
```yml
media_library:
name: cloudinary
config:
cloud_name: your_cloud_name
api_key: your_api_key
```
## Netlify CMS configuration options
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`).
* **`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`.
## Cloudinary configuration options
The Cloudinary media library integration can be configured in two ways: globally and per field. Global options will be overridden by field options. All options are listed in Cloudinary's [media library documentation](https://cloudinary.com/documentation/media_library_widget#3_set_the_configuration_options), but only the following options are available or recommended for the Netlify CMS integration:
### Authentication
* `cloud_name`
* `api_key`
* `username` _\- pre-fills a username in the Cloudinary login form_
### Media library behavior
* `default_transformations` _\- only the first [image transformation](#image-transformations) is used, be sure to use the `Library` column transformation names from the_ [_transformation reference_]("https://cloudinary.com/documentation/image_transformation_reference")
* `max_files`
* `multiple` _\- has no impact on images inside the [markdown widget](/docs/widgets/#markdown)_
## Image transformations
The Cloudinary integration allows images to be transformed in two ways: directly within Netlify CMS, and separately from the CMS via Cloudinary's [dynamic URL's](https://cloudinary.com/documentation/image_transformations#delivering_media_assets_using_dynamic_urls). If you transform images 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.
## Art direction and responsive images
If you prefer to provide art 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:
1. Either globally or for specific fields, configure the Cloudinary extension to only output the asset filename:
```yml
# global
media_library:
name: cloudinary
output_filename_only: true
# field
fields:
- { name: image, widget: image, media_library: { output_filename_only: true } }
```
2. Provide a dynamic URL in the site template where the image is used:
```hbs
{{! handlebars example }}
<img src="https://res.cloudinary.com/<cloud_name>/<resource_type>/<type>/<version>/<transformations>/{{image}}"/>
```
Your dynamic URL can be formed conditionally to provide any desired transformations - please see Cloudinary's [image transformation reference](https://cloudinary.com/documentation/image_transformation_reference) for available transformations.

View File

@ -73,9 +73,8 @@ For example:
name: cover
label: Cover Image
widget: image
options:
media_library:
config:
multiple: true
previewStep: false
media_library:
config:
multiple: true
previewStep: false
```

View File

@ -7,13 +7,21 @@ The file widget allows editors to upload a file or select an existing one from t
- **Name:** `file`
- **UI:** file picker button opens media gallery
- **Data type:** file path string, based on `media_folder`/`public_folder` configuration
- **Data type:** file path string
- **Options:**
- `default`: accepts a file path string; defaults to null
- `media_library`: media library settings to apply when a media library is opened by the
current widget
- `allow_multiple`: _(default: `true`)_ when set to `false`, prevents multiple selection for any media library extension, but must be supported by the extension in use
- `config`: a configuration object that will be passed directly to the media library being
used - available options are determined by the library
- **Example:**
```yaml
- label: "Manual PDF"
name: "manual_pdf"
widget: "file"
default: "/uploads/general-manual.pdf"
media_library:
config:
multiple: true
```

View File

@ -7,11 +7,12 @@ The image widget allows editors to upload an image or select an existing one fro
- **Name:** `image`
- **UI:** file picker button opens media gallery allowing image files (jpg, jpeg, webp, gif, png, bmp, tiff, svg) only; displays selected image thumbnail
- **Data type:** file path string, based on `media_folder`/`public_folder` configuration
- **Data type:** file path string
- **Options:**
- `default`: accepts a file path string; defaults to null
- `media_library`: media library settings to apply when a media library is opened by the
current widget
- `allow_multiple`: _(default: `true`)_ when set to `false`, prevents multiple selection for any media library extension, but must be supported by the extension in use
- `config`: a configuration object that will be passed directly to the media library being
used - available options are determined by the library
- **Example:**
@ -22,6 +23,5 @@ The image widget allows editors to upload an image or select an existing one fro
default: "/uploads/chocolate-dogecoin.jpg"
media_library:
config:
publicKey: "demopublickey"
multiple: true
```