docs: add docs

cloudinary-community · Nov 8, 2020 · dfb8657 · dfb8657
1 parent 6e266d1
commit dfb8657
Show file tree

Hide file tree

Showing 25 changed files with 869 additions and 257 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # Manage your images with Cloudinary in Gridsome apps
 
+[![Netlify Status](https://api.netlify.com/api/v1/badges/26ef3048-66c3-46a7-b719-49dcfd1dcd85/deploy-status)](https://app.netlify.com/sites/gridsome-cloudinary/deploys)
+
 > [Cloudinary](https://cloudinary.com) integration for [Gridsome](https://gridsome.org)
 
 [Demo site](https://gridsome-cloudinary.netlify.app/)

diff --git a/docs/docs/general-plugin/general-plugin.md → ...ary-transformer/cloudinary-transformer.md b/docs/docs/general-plugin/general-plugin.md → ...ary-transformer/cloudinary-transformer.md
@@ -1,8 +1,7 @@
 ---
 title: Setup
-slug: image-optimizer
-category: Image Optimizer Plugin
-description: A simple way to get existing Cloudinary assets to use in Gridsome apps with optimization
+slug: cloudinary-transformer
+category: Cloudinary Image Transformer
 categoryPosition: 3
 position: 1
 ---
@@ -24,7 +23,7 @@ You can set up the source plugin easily in two following steps:
   npm i gridsome-plugin-cloudinary
   ```
 
-2. Add `gridsome-plugin-cloudinary` as a plugin to `plugins` section of `nuxt.config.js`:
+2. Add `gridsome-plugin-cloudinary` as a plugin to `plugins` section of `gridsome.config.js`:
 
   ```js
   /* gridsome.config.js */
@@ -41,6 +40,6 @@ You can set up the source plugin easily in two following steps:
   }
   ```
 
-See [Options](#configure-options) for all available options to initialize Cloudinary source plugin.
+See [Options](/cloudinary-transformer-options) for all available options to initialize Cloudinary source plugin.
 
 And that's it 🎉!
diff --git a/docs/docs/general-plugin/configurations.md → .../cloudinary-transformer/configurations.md b/docs/docs/general-plugin/configurations.md → .../cloudinary-transformer/configurations.md
@@ -1,11 +1,11 @@
 ---
 title: Options
-slug: image-optimizer-options
-category: Image Optimizer Plugin
+slug: cloudinary-transformer-options
+category: Cloudinary Image Transformer
 position: 2
 ---
 
-To set configurations for Cloudinary source plugin, we use inner `options` section of the `gridsome-plugin-cloudinary` in `gridsome.config.js`.
+To set configurations for Cloudinary image transformer, we use inner `options` section of the `gridsome-plugin-cloudinary` in `gridsome.config.js`.
 
 The list of available options are shown as below
 
@@ -14,7 +14,7 @@ The list of available options are shown as below
 * Type: `String`
 * `required`
 
-The cloud name associated with your Cloudinary account. It is used to configure and enable Cloudinary features such as generating delivery asset URL. 
+The cloud name associated with your Cloudinary account. It is used to configure and enable Cloudinary features such as generating delivery asset URL.
 
 ```js
 /* gridsome.config.js */

diff --git a/docs/docs/cloudinary-transformer/usage.md b/docs/docs/cloudinary-transformer/usage.md
@@ -0,0 +1,20 @@
+---
+title: Usage
+slug: cloudinary-transformer-usage
+category: Cloudinary Image Transformer
+position: 3
+---
+
+To use the plugin, you need to have an account with [Cloudinary](https://cloudinary.com/users/register/free) and have your media files stored on Cloudinary. 
+
+This plugin fetches the desired media files from your Cloudinary account to the Gridsome's Data layer, and transforms them into two set of images - fixed and responsive. The approach is based on `srcset` of `img` tag, as indicated in [Responsive image documentation](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
+
+Upon querying, the transformer expose the media file under the schema `CldAsset`. You can then query your media using GraphQL, and apply further transformations for a fixed-width image, or responsive image.
+
+## Fixed-width images
+
+## Responsive images
+
+## GIF images
+
+## Manual creating Cloudinary data for Gridsome image
diff --git a/docs/docs/general-plugin/usage.md b/docs/docs/general-plugin/usage.md
diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
@@ -15,7 +15,7 @@ View our [Demo site](/demo) for some examples.
 
 ## Available plugins
 
-[Image transformer](/image-transformer) · [Source plugin](/source-plugin) · [General plugin](/general-plugin)
+[Generic Image Transformer](/image-transformer) · [Cloudinary Source Plugin](/source-plugin) · [Cloudinary Transformer](/cloudinary-transformer)
 
 ## What is Cloudinary?
 

diff --git a/docs/docs/image-transformer/configurations.md b/docs/docs/image-transformer/configurations.md
@@ -5,184 +5,64 @@ category: Image Transformer
 position: 2
 ---
 
-To set configurations for Cloudinary source plugin, we use inner `options` section of the `gridsome-transformer-img` in `gridsome.config.js`.
-
-The list of available options are shown as below
-
-### `cloudName` - Required
-
-* Type: `String`
-* `required`
-
-The cloud name associated with your Cloudinary account. It is used to configure and enable Cloudinary features such as generating delivery asset URL. 
-
-```js
-/* gridsome.config.js */
-
-export default {
-  plugins: [
-    {
-      use: 'gridsome-transformer-img',
-      options: {
-        cloudName: 'your-cloud-name'
-      }
-    },
-  ]
-}
-```
-
-Cloud name presents in every delivered URL from Cloudinary, hence it's important to have it configured correctly.
-
-You can find your cloud name details in **Dashboard** page, or in **Account Settings** page in [Cloudinary console](https://cloudinary.com/console)
-
-### `apiKey` - Required
-
-* Type: `String`
-* `required`
-
-The API Key associated with your Cloudinary account. It is used together with `apiSecret` to query images and videos from your Cloudinary account to GraphQL Data Layer.
+For adding extra configurations for the transformer plugin, we add `img` field to the `transformers` section of `gridsome.config.js`.
 
 ```js
 /* gridsome.config.js */
-
-export default {
-  plugins: [
-    {
-      use: 'gridsome-transformer-img',
-      options: {
-        apiKey: 'your-api-key'
-      }
-    },
-  ]
-}
-```
-
-You can find your API Key in your **Cloudinary Dashboard** page, or in **Settings/Security** page in [Cloudinary console](https://cloudinary.com/console)
-
-![How to find apiKey in Cloudinary Console](https://res.cloudinary.com/mayashavin/image/upload/f_auto,q_auto,w_730/v1601805482/nuxt-cld/apikey)
-
-**Warning** These private keys should be kept as environment variables in `.env`.
-
-## `apiSecret` - Required
-
-* Type: `String`
-* `required`
-
-The API Secret Key associated with your Cloudinary account. It is used together with `apiKey` to query images and videos from your Cloudinary account to GraphQL Data Layer.
-
-```js
-/* gridsome.config.js */
-
-export default {
-  plugins: [
-    {
-      use: 'gridsome-transformer-img',
-      options: {
-        apiSecret: 'your-api-secret-key'
+  export default {
+    transformers: {
+      img: {
+        /* Extra configurations */
       }
     }
-  ]
-}
+  }
 ```
 
-You can find your API Secret Key in your **Cloudinary Dashboard** page, or in **Settings/Security** page in [Cloudinary console](https://cloudinary.com/console).
-
-![How to find apiSecret in Cloudinary Console](https://res.cloudinary.com/mayashavin/image/upload/f_auto,q_auto,w_730/v1601805482/nuxt-cld/apikey_2)
-
-**Warning** These private keys should be kept as environment variables in `.env`.
-
-## `secure`
-
-* Type: `Boolean`
-* Default: `true`
-
-Force secure HTTPS delivery urls for all assets (images + videos) generated by Cloudinary, even if they are embedded in HTTP originally.
-
-Disable this flag to have all delivery urls built with HTTP protocol instead.
-
-```js
-/* gridsome.config.js */
-
-export default {
-  plugins: [
-    {
-      use: 'gridsome-transformer-img',
-      options: {
-        secure: false
-      }
-    },
-  ]
-}
-```
+The list of available options are shown as below:
 
-## `secureDistribution`
+### `uploadOptions`
 
-* Type: `String`
-* Relevant only when `secure` is `true`
+* Type: `Object`
 
-Set custom domain name for building **secure HTTPS** urls.
+Contains the upload configurations for uploading and processing the images by a loader. 
 
 ```js
 /* gridsome.config.js */
-
 export default {
-  plugins: [
-    {
-      use: 'gridsome-transformer-img',
-      options: {
-        secureDistribution: 'your-custome-domain-name'
-      }
-    },
-  ]
+  transformers: {
+    img: {
+      uploadOptions: {
+        folder: 'examples',
+      },
+    }
+  }
 }
 ```
 
-Only relevant if you are Advanced plan Cloudinary user with private CDN distribution and custom CNAME set. You can see [more details here](https://cloudinary.com/documentation/advanced_url_delivery_options#private_cdns_and_cnames)
-
-## `cname`
-
-* Type: `String`
-* Use **only** when `secure` is `false`
-
-Set custom domain name for building **non-secure HTTP** urls.
-
-```js
-/* gridsome.config.js */
-
-export default {
-  plugins: [
-    {
-      use: 'gridsome-transformer-img',
-      options: {
-        cname: 'your-custome-domain-name'
-      }
-    },
-  ]
-}
-```
+It currently accept the following properties:
 
-Only relevant if you are Advanced plan Cloudinary user with private CDN distribution and custom CNAME set. You can see [more details here](https://cloudinary.com/documentation/advanced_url_delivery_options#private_cdns_and_cnames)
+Property | Type | Default | Required | Description
+--- | --- | --- | --- | ---
+`folder` | string | `` | no | The directory where the images should be uploaded to.
 
-## `privateCdn`
+### `loader`
 
-* Type: `Boolean`
-* Default: `false`
+* Type: `Object`
+* **Required** when `img.uploadOptions` is used.
 
-Set to `true` if you'd like to use private CDN distribution.
+Indicate which image optimizing loader should be used through `loader.type` and other required configurations for that specific loader.
 
 ```js
-/* gridsome.config.js */
-
 export default {
-  plugins: [
-    {
-      use: 'gridsome-transformer-img',
-      options: {
-        privateCdn: true
+  transformers: {
+    img: {
+      loader: {
+        type: 'cloudinary',
+        /* Cloudinary configurations */
       }
-    },
-  ]
+    }
+  }
 }
 ```
 
-Only relevant for Advanced plan Cloudinary users. You can see [more details here](https://cloudinary.com/documentation/advanced_url_delivery_options#private_cdns_and_cnames)
+View [Loader](/image-transformer-loader) for types and required configurations per loader supported.
diff --git a/docs/docs/image-transformer/image-transformer.md b/docs/docs/image-transformer/image-transformer.md
@@ -3,13 +3,16 @@ title: Setup
 slug: image-transformer
 category: Image Transformer
 categoryPosition: 1
-description: A simple way to get existing Cloudinary assets to use in Gridsome apps with optimization
 position: 1
 ---
 
 [Demo site](/demo)
 
-You can set up the source plugin easily by:
+Automatic image handling by Gridsome is great, but sometimes we need a bit more. For example: having them uploaded to and optimized by Cloudinary when querying them from Gridsome's data layer.
+
+The workflow stays the same: add images to your side, have `@gridsome/source-filesystem` read them, and then query them to use in your components.
+
+Image transformer tool give you that freedom out of the box, by folloing the below steps:
 
 ## Installation
 
@@ -31,7 +34,7 @@ You can set up the source plugin easily by:
   npm i gridsome-transformer-img
   ```
 
-3. Add `@gridsome/source-filesystem` as plugins to `plugins` section of `nuxt.config.js` and request for the desired images:
+3. Add `@gridsome/source-filesystem` as plugins to `plugins` section of `gridsome.config.js` and request for the desired images:
 
   ```js
   /* gridsome.config.js */
@@ -41,13 +44,43 @@ You can set up the source plugin easily by:
       {
         use: '@gridsome/source-filesystem',
         options: {
-          path: 'content/images',
+          path: 'path-to-local-images',
         }
       },
     ]
   }
   ```
 
-3. Choose a loader to optimizer your images.
+3. *Optional* - Set up your upload options and choose a `loader` to optimize your images in `img` section of `transformer` in `gridsome.config.js`.
+
+  ```js
+  /* gridsome.config.js */
+
+  export default {
+    plugins: [
+      {
+        use: '@gridsome/source-filesystem',
+        options: {
+          path: 'path-to-local-images',
+        }
+      },
+    ],
+    transformers: {
+      img: {
+        uploadOptions: {
+          folder: 'examples', //directory path in cloudinary where asset should be uploaded to
+        },
+        loader: {
+          type: 'cloudinary',
+          cloudName: process.env.CLOUDNAME,
+          apiKey: process.env.API_KEY,
+          apiSecret: process.env.API_SECRET,
+        }
+      }
+    }
+  }
+  ```
+
+See [Loader](/image-transformer-loader) for more details on the available loader services, and [Options](/image-transfomer-options) for other configuration options.
 
-And that's it 🎉! You can start querying your images in the Data Layer
+And that's it 🎉! You can start querying your images in the Data Layer.