Refactor readme examples (#206)

* Refactor readme examples

* add combined example

* Rephrase titles

* Fix readme typo

Co-authored-by: Pierre Wizla <[email protected]>

Co-authored-by: Pierre Wizla <[email protected]>

Author: remidej

README.md

@@ -4,11 +4,42 @@ Source plugin for pulling documents into Gatsby from a Strapi API.
 
 > **WARNING**: This is the README for v1.0.0 which is in `alpha` version for now. Make sure to install it with @alpha to try it out. It's designed to be used with Gatsby v3.
 
-## Install
+## Installing the plugin
 
-`npm install --save gatsby-source-strapi@alpha`
+```sh
+# Using Yarn
+yarn add gatsby-source-strapi@alpha
 
-## How to use
+# Or using NPM
+npm install --save gatsby-source-strapi@alpha
+```
+
+## Setting up the plugin
+
+You can enable and configure this plugin in your `gatsby-config.js` file.
+
+### Basic usage
+
+```javascript
+// In your gatsby-config.js
+plugins: [
+  {
+    resolve: `gatsby-source-strapi`,
+    options: {
+      apiURL: `http://localhost:1337`,
+      queryLimit: 1000, // Defaults to 100
+      collectionTypes: [`article`, `user`],
+      singleTypes: [`home-page`, `contact`],
+    },
+  },
+];
+```
+
+### Advanced usage
+
+#### Custom endpoint
+
+By default, we use the pluralize module to deduct the endpoint that matches a collection type. You can opt out of this behavior. To do so, pass an entity definition object with your custom endpoint.
 
 ```javascript
 // In your gatsby-config.js
@@ -17,30 +48,63 @@ plugins: [
     resolve: `gatsby-source-strapi`,
     options: {
       apiURL: `http://localhost:1337`,
-      queryLimit: 1000, // Default to 100
       collectionTypes: [
-        `article`,
-        `user`,
-        // if you don't want to leave the definition of an api endpoint to the pluralize module
         {
           name: `collection-name`,
           endpoint: `custom-endpoint`,
         },
-        // if you want to use custom query strings (e.g. to fetch all locales)
-        // mapping of api.qs object will be used to create final query string (e.g: http://localhost:1337/collection-name?_locale=all)
+      ]
+    },
+  },
+];
+```
+
+#### Internationalization support
+
+Strapi now supports [internationalization](https://strapi.io/documentation/developer-docs/latest/development/plugins/i18n.html#installation). But by default, this plugin will only fetch data in the default locale of your Strapi app. If your content types are available in different locales, you can also pass an entity definition object to specify the locale you want to fetch for a content type. Use the `all` value to get all available locales.
+
+```javascript
+// In your gatsby-config.js
+plugins: [
+  {
+    resolve: `gatsby-source-strapi`,
+    options: {
+      apiURL: `http://localhost:1337`,
+      collectionTypes: [
+        // Fetch all locales for collection-name
         {
           name: `collection-name`,
-          api: { qs: { _locale: 'all' } }
+          api: { qs: { _locale: `all` } }
         },
-        // exemple fetching only english content
+        // Only fetch english content for other-collection-name
         {
-          name: `collection-name`,
-          api: { qs: { _locale: 'en' } }
+          name: `other-collection-name`,
+          api: { qs: { _locale: `en` } }
         },
-      ],
-      //If using single types place them in this array.
-      singleTypes: [`home-page`, `contact`],
-      // Possibility to login with a strapi user, when content types are not publically available (optional).
+        // Combined with a custom endpoint
+        {
+          name: `another-collection-name`,
+          endpoint: `custom-endpoint`,
+          api: { qs: { _locale: `en` } }
+        },
+      ]
+    },
+  },
+];
+```
+
+#### Authenticated requests
+
+Strapi's [Roles & Permissions plugin](https://strapi.io/documentation/developer-docs/latest/development/plugins/users-permissions.html#concept) allows you to protect your API actions. If you need to access a route that is only available to a logged in user, you can provide your credentials so that this plugin can access to the protected data.
+
+```javascript
+// In your gatsby-config.js
+plugins: [
+  {
+    resolve: `gatsby-source-strapi`,
+    options: {
+      apiURL: `http://localhost:1337`,
+      collectionTypes: [`collection-name`],
       loginData: {
         identifier: '',
         password: '',
@@ -50,7 +114,7 @@ plugins: [
 ];
 ```
 
-## How to query
+## Querying data
 
 You can query Document nodes created from your Strapi API like the following:
 
@@ -86,7 +150,6 @@ Make sure to add `api.qs._locale` to your strapi configuration in `gatsby-config
 }
 ```
 
-
 To query images you can do the following:
 
 ```graphql