Feature/docs (#67)
This commit is contained in:
Daniel Lautzenheiser
committed by
GitHub
GitHub
parent
7a1ec55a5c
commit
81ca566b5e
@ -3,6 +3,9 @@ group: Media
|
||||
title: Cloudinary
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## <img src="https://img.shields.io/badge/-Beta%20Feature-blue" alt="Beta Feature. Use at your own risk" title="Beta Feature. Use at your own risk" />
|
||||
|
||||
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 Static CMS uses Cloudinary's own media library interface within Static CMS. To get started, you'll need a Cloudinary account and Static CMS 2.3.0 or greater.
|
||||
@ -13,32 +16,33 @@ You can [sign up for Cloudinary](https://cloudinary.com/users/register/free) for
|
||||
|
||||
|
||||
|
||||
## Connecting Cloudinary to Static CMS
|
||||
## Connecting Cloudinary
|
||||
|
||||
To use the Cloudinary media library within Static CMS, you'll need to update your Static CMS configuration file with the information from your Cloudinary account:
|
||||
|
||||
```yaml
|
||||
media_library:
|
||||
title: cloudinary
|
||||
name: cloudinary
|
||||
config:
|
||||
cloud_title: your_cloud_name
|
||||
cloud_name: your_cloud_name
|
||||
api_key: your_api_key
|
||||
```
|
||||
|
||||
**Note:** The user must be logged in to the Cloudinary account connected to the `api_key` used in your Static CMS configuration.
|
||||
**Note:** The user must be logged in to the Cloudinary account connected to the `api_key` used in your Static CMS configuration.
|
||||
|
||||
### Security Considerations
|
||||
|
||||
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`.
|
||||
|
||||
## Static CMS configuration options
|
||||
|
||||
The following options are specific to the Static CMS integration for Cloudinary:
|
||||
|
||||
* **`output_filename_only`**: _(default: `false`)_\
|
||||
- **`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](#inserting-cloudinary-url-in-page-templates).
|
||||
* **`use_transformations`**: _(default: `true`)_\
|
||||
- **`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`)_\
|
||||
- **`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
|
||||
@ -47,20 +51,21 @@ The following options are used to configure the media library. All options are l
|
||||
|
||||
### Authentication
|
||||
|
||||
* `cloud_name`
|
||||
* `api_key`
|
||||
- `cloud_name`
|
||||
- `api_key`
|
||||
|
||||
### Media library behavior
|
||||
|
||||
* `default_transformations` _\- only the first [image transformation](#image-transformations) is used, be sure to use the `SDK Parameter` column transformation names from the_ [_transformation reference_](https://cloudinary.com/documentation/image_transformation_reference)
|
||||
* `max_files` _\- has no impact on images inside the [markdown widget](/docs/widgets/#markdown)_. Refer to [media library documentation](https://cloudinary.com/documentation/media_library_widget#3_set_the_configuration_options) for details on this property
|
||||
* `multiple` _\- has no impact on images inside the [markdown widget](/docs/widgets/#markdown)_. Refer to [media library documentation](https://cloudinary.com/documentation/media_library_widget#3_set_the_configuration_options) for details on this property
|
||||
- `default_transformations` _\- only the first [image transformation](#image-transformations) is used, be sure to use the `SDK Parameter` column transformation names from the_ [_transformation reference_](https://cloudinary.com/documentation/image_transformation_reference)
|
||||
- `max_files` _\- has no impact on images inside the [markdown widget](/docs/widgets/#markdown)_. Refer to [media library documentation](https://cloudinary.com/documentation/media_library_widget#3_set_the_configuration_options) for details on this property
|
||||
- `multiple` _\- has no impact on images inside the [markdown widget](/docs/widgets/#markdown)_. Refer to [media library documentation](https://cloudinary.com/documentation/media_library_widget#3_set_the_configuration_options) for details on this property
|
||||
|
||||
## Image transformations
|
||||
|
||||
The Cloudinary integration allows images to be transformed in two ways: directly within Static CMS via [Cloudinary's Media Library](#transforming-images-via-media-library), and separately from the CMS via Cloudinary's [dynamic URL's](https://cloudinary.com/documentation/image_transformations#delivering_media_assets_using_dynamic_urls) by [inserting cloudinary urls](#inserting-cloudinary-url-in-page-templates).
|
||||
|
||||
### Transforming images via Media Library
|
||||
### Transforming Images
|
||||
|
||||
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](#global-configuration) and per [field](#field-configuration). Global options will be overridden by field options.
|
||||
|
||||
@ -73,7 +78,7 @@ instance of the Cloudinary widget.
|
||||
```yaml
|
||||
# global
|
||||
media_library:
|
||||
title: cloudinary
|
||||
name: cloudinary
|
||||
output_filename_only: false
|
||||
config:
|
||||
default_transformations:
|
||||
@ -92,43 +97,45 @@ For example:
|
||||
```yaml
|
||||
# field
|
||||
fields: # The fields each document in this collection have
|
||||
- label: 'Cover Image'
|
||||
title: 'image'
|
||||
widget: 'image'
|
||||
required: false
|
||||
tagtitle: ''
|
||||
media_library:
|
||||
config:
|
||||
default_transformations:
|
||||
- fetch_format: auto
|
||||
width: 300
|
||||
quality: auto
|
||||
crop: fill
|
||||
effect: grayscale
|
||||
- label: 'Cover Image'
|
||||
name: 'image'
|
||||
widget: 'image'
|
||||
required: false
|
||||
tagtitle: ''
|
||||
media_library:
|
||||
config:
|
||||
default_transformations:
|
||||
- fetch_format: auto
|
||||
width: 300
|
||||
quality: auto
|
||||
crop: fill
|
||||
effect: grayscale
|
||||
```
|
||||
|
||||
## Inserting Cloudinary URL in page templates
|
||||
|
||||
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
|
||||
- Either globally or for specific fields, configure the Cloudinary extension to only output the asset filename
|
||||
|
||||
```yaml
|
||||
# global
|
||||
media_library:
|
||||
title: cloudinary
|
||||
name: cloudinary
|
||||
output_filename_only: true
|
||||
# field
|
||||
media_library:
|
||||
title: cloudinary
|
||||
name: cloudinary
|
||||
output_filename_only: true
|
||||
```
|
||||
|
||||
* Provide a dynamic URL in the site template
|
||||
- Provide a dynamic URL in the site template
|
||||
|
||||
```handlebars
|
||||
{{! handlebars example }}
|
||||
<img src="https://res.cloudinary.com/<cloud_name>/<resource_type>/<type>/<transformations>/{{image}}"/>
|
||||
<img
|
||||
src='https://res.cloudinary.com/<cloud_name>/<resource_type>/<type>/<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.
|
||||
|
||||
Reference in New Issue
Block a user