Skip to content

Commit

Permalink
add documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@raae
raae committed Nov 30, 2022
1 parent eb6bab9 commit 5ff9bcd
Showing 1 changed file with 25 additions and 17 deletions.
42 changes: 25 additions & 17 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -255,23 +255,24 @@ The property `defaultTracedSVG` in the node above can be used by your CMS/backen

In `gatsby-config.js` the plugin accepts the following options:

| option | type | required | default value | description |
| --------------------------------------------------- | ---------- | -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cloudName` | `String` | false | n/a | Cloud name of your Cloudinary account, can be obtained from your [Cloudinary console](https://cloudinary.com/console/). This should be stored and retrieved as an environment variable. |
| `apiKey` | `String` | false | n/a | API Key of your Cloudinary account, can be obtained from your [Cloudinary console](https://cloudinary.com/console/). This should be stored and retrieved as an environment variable. |
| `apiSecret` | `String` | false | n/a | API Secret of your Cloudinary account, can be obtained from your [Cloudinary console](https://cloudinary.com/console/). This should be stored and retrieved as an environment variable. |
| `uploadFolder` | `String` | false | n/a | An optional folder name where the uploaded assets will be stored on Cloudinary. |
| `uploadSourceInstanceNames` | `[String]` | false | n/a | An optional array limiting uploads to file nodes with a matching sourceInstanceName. |
| `transformTypes` | `[String]` | false | `['CloudinaryAsset']` | An optional array of GraphQL Types needing Gatsby Image support. Adds the resolvers `gatsbyImageData`, `fluid` (deprecated) and `fixed` (deprecated)). |
| `overwriteExisting` | `Boolean` | false | false | Whether to overwrite existing assets with the same public ID. When set to false, return immediately if an asset with the same Public ID was found. It's recommended that this is set to false in development as each image overwrite costs one Cloudinary transformation. |
| `defaultTransformations` (gatsby-plugin-image only) | `[String]` | false | ` ['c_fill', 'g_auto', 'q_auto']` | The default value for the `gatsbyImageData` resolver argument `transformations`. |
| `fluidMaxWidth` (gatsby-image only) | `Int` | false | 1000 | The maximum width needed for an image. If specifying a width bigger than the original image, the width of the original image is used instead. Used when calculating breakpoints. |
| `fluidMinWidth` (gatsby-image only) | `Int` | false | 200 | The minimum width needed for an image. Used when calculating breakpoints. |
| `createDerived` (gatsby-image only) | `Boolean` | false | true | If `true`, create and keep the derived images of the selected breakpoints during the API call. If false, images generated during the analysis process are thrown away. This option is ignored if `useCloudinaryBreakpoints` is `false`. It's recommended that you enable `createDerived` if `useCloudinaryBreakpoints` is true to store the breakpoint images and prevent them from being recalculated on every build. |
| `breakpointsMaxImages` (gatsby-image only) | `Integer` | false | 5 | Set maximum number of responsive breakpoint images generated and returned on image upload. If `useCloudinaryBreakpoints` is false, then exactly `breakpointsMaxImages` breakpoints will be created. |
| `useCloudinaryBreakpoints` (gatsby-image only) | `Boolean` | false | false | If `true`, then Cloudinary will be requested to automatically find the best breakpoints for each image. It's recommended that this option be set to `false` in development because this option uses one Cloudinary transformation for every image uploaded to Cloudinary plus one transformation for every derived image created while calculating breakpoints. |
| `enableDefaultTransformations` (gatsby-image only) | `Boolean` | false | false | `true` will add the `q_auto` and `f_auto` transformations to images for quality and format optimizations. |
| `alwaysUseDefaultBase64` (gatsby-image only) | `Boolean` | false | false | When `alwaysUseDefaultBase64` is true, `gatsby-transformer-cloudinary` will always use `defaultBase64` images when they are provided to the GraphQL layer. It's recommended that you set `alwaysUseDefaultBase64` to true in your development environment and provide `defaultBase64` properties for any images already uploaded to Cloudinary. Doing so will result in faster and cheaper builds because no Cloudinary API calls will need to be made when resolving your GraphQL queries. |
| option | type | required | default value | description |
| --------------------------------------------------- | ---------- | -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cloudName` | `String` | false | n/a | Cloud name of your Cloudinary account, can be obtained from your [Cloudinary console](https://cloudinary.com/console/). This should be stored and retrieved as an environment variable. |
| `apiKey` | `String` | false | n/a | API Key of your Cloudinary account, can be obtained from your [Cloudinary console](https://cloudinary.com/console/). This should be stored and retrieved as an environment variable. |
| `apiSecret` | `String` | false | n/a | API Secret of your Cloudinary account, can be obtained from your [Cloudinary console](https://cloudinary.com/console/). This should be stored and retrieved as an environment variable. |
| `uploadFolder` | `String` | false | n/a | An optional folder name where the uploaded assets will be stored on Cloudinary. |
| `uploadSourceInstanceNames` | `[String]` | false | n/a | An optional array limiting uploads to file nodes with a matching sourceInstanceName. |
| `transformTypes` | `[String]` | false | `['CloudinaryAsset']` | An optional array of GraphQL Types needing Gatsby Image support. Adds the resolvers `gatsbyImageData`, `fluid` (deprecated) and `fixed` (deprecated)). |
| `overwriteExisting` | `Boolean` | false | false | Whether to overwrite existing assets with the same public ID. When set to false, return immediately if an asset with the same Public ID was found. It's recommended that this is set to false in development as each image overwrite costs one Cloudinary transformation. |
| `defaultTransformations` (gatsby-plugin-image only) | `[String]` | false | ` ['c_fill', 'g_auto', 'q_auto']` | The default value for the `gatsbyImageData` resolver argument `transformations`. |

| `fluidMaxWidth` (gatsby-image only) | `Int` | false | 1000 | The maximum width needed for an image. If specifying a width bigger than the original image, the width of the original image is used instead. Used when calculating breakpoints. |
| `fluidMinWidth` (gatsby-image only) | `Int` | false | 200 | The minimum width needed for an image. Used when calculating breakpoints. |
| `createDerived` (gatsby-image only) | `Boolean` | false | true | If `true`, create and keep the derived images of the selected breakpoints during the API call. If false, images generated during the analysis process are thrown away. This option is ignored if `useCloudinaryBreakpoints` is `false`. It's recommended that you enable `createDerived` if `useCloudinaryBreakpoints` is true to store the breakpoint images and prevent them from being recalculated on every build. |
| `breakpointsMaxImages` (gatsby-image only) | `Integer` | false | 5 | Set maximum number of responsive breakpoint images generated and returned on image upload. If `useCloudinaryBreakpoints` is false, then exactly `breakpointsMaxImages` breakpoints will be created. |
| `useCloudinaryBreakpoints` (gatsby-image only) | `Boolean` | false | false | If `true`, then Cloudinary will be requested to automatically find the best breakpoints for each image. It's recommended that this option be set to `false` in development because this option uses one Cloudinary transformation for every image uploaded to Cloudinary plus one transformation for every derived image created while calculating breakpoints. |
| `enableDefaultTransformations` (gatsby-image only) | `Boolean` | false | false | `true` will add the `q_auto` and `f_auto` transformations to images for quality and format optimizations. |
| `alwaysUseDefaultBase64` (gatsby-image only) | `Boolean` | false | false | When `alwaysUseDefaultBase64` is true, `gatsby-transformer-cloudinary` will always use `defaultBase64` images when they are provided to the GraphQL layer. It's recommended that you set `alwaysUseDefaultBase64` to true in your development environment and provide `defaultBase64` properties for any images already uploaded to Cloudinary. Doing so will result in faster and cheaper builds because no Cloudinary API calls will need to be made when resolving your GraphQL queries. |

The options `cloudName`, `apiKey`, and `apiSecret` are required if any images will be uploaded to Cloudinary during the build process. If you're solely using images already uploaded to Cloudinary, then these options can be safely omitted.

Expand Down Expand Up @@ -315,6 +316,13 @@ The style of the temporary image shown while the larger image is loaded.
Go to the [Gatsby Plugin Image Docs](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image/#placeholder) for more information.

#### `secure`

When set to `false` uses `http` instead of `https` for the image urls.

**Type:** `Boolean`
**Default:** `true`

#### `height` / `width`

Go to the [Gatsby Plugin Image Docs](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image/#widthheight) for information on `height` / `width`.
Expand Down

0 comments on commit 5ff9bcd

Please sign in to comment.