Merge pull request #145 from collective/update-docs

Update documentation

docs/index.md

@@ -1,8 +1,20 @@
 # gatsby-source-plone
 
-Gatsby is a blazing fast static site generator for React. By using Plone as source, this can be used to generate a static site with PWA features with something equivalent to the click of a button. That’s the essence of the **“Big Green Button”** proposal, according to **Martin Aspeli**, who wrote a blog post **"[Pete and Andy try Plone 4](http://www.martinaspeli.net/articles/pete-and-andy-try-plone-4)"**:
+[GatsbyJS](https://www.gatsbyjs.org/) is a generator for blazing fast static web sites or web apps powered by pre-rendered [ReactJS](https://reactjs.org/). With this plugin, you can build any amount of gatsby sites from a single [Plone CMS](https://plone.org/), the ultimate open source enterprise CMS.
 
-_"Andy goes to Plone's Deployment control panel. There he finds a Big Green Button.
-He pushes it and covers his eyes. A minute later, a bunch of static HTML files appear in a directory on the server, covering the Plone site, with basic navigation and a site map. Search is provided via a form that posts to Google for search results on the current site."_
+This gatsby-source plugin pulls the whole content tree from a Plone site (or its sub-folder) using [Plone REST API](https://plonerestapi.readthedocs.io/en/latest/) and makes it available for querying via GraphQL in a Gatsby based project.
 
-A gatsby-source plugin pulls the whole content tree from the plone.restapi and makes it available for querying via GraphQL in a hierarchical data structure. The gatsby-plone-starter that uses the plugin to source the data from a Plone site will illustrate all use cases of the plugin in a Gatsby project.
+Common use-cases include to
+
+* spin-off practically unlimited amount of individually hosted, branded and featured static sites from content managed in a single Plone instance without side-effects to the Plone instance in question
+
+* allow mixed use of Plone, where small individually branded ˝poster sites˝ could be published from larger Plone site with unified theme without need for hosting secondary CMS instances for a such need
+
+* build mash-ups mixin Plone content with content from file-system or other sources.
+
+No Plone knowledge should be required to use this plugin. Just follow the examples in gatsby-starter-plone and the official Gatsby user documentation.
+
+A Plone add-on [collective.webhook](https://pypi.org/project/collective.webhook/) can be used to trigger CI pipelines to rebuild and deploy sites after any change in Plone content.
+
+_˝Andy goes to Plone’s Deployment control panel. There he finds a Big Green Button.
+He pushes it and covers his eyes. A minute later, a bunch of static HTML files appear in a directory on the server, covering the Plone site, with basic navigation and a site map. Search is provided via a form that posts to Google for search results on the current site.˝_ –Martin Aspeli, 2009, ˝[Pete and Andy try Plone 4](http://www.martinaspeli.net/articles/pete-and-andy-try-plone-4)˝

docs/publish.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-baseUrl="http://localhost:8080/Plone/docs"
+baseUrl="http://localhost:8080/Plone"
 
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 marked="$DIR/../node_modules/.bin/marked"

docs/reference/authentication.md

@@ -0,0 +1,59 @@
+# Authenticating REST API calls
+
+For Plone sites requiring authentication to use Plone REST API (or limiting publishable content by permissions of specific user) you may use this guide to set up a safe method of authentication using [JWT](http://plonerestapi.readthedocs.io/en/latest/authentication.html#json-web-tokens-jwt) and [dotenv](https://github.com/motdotla/dotenv) configuration.
+
+**Note:** In time of writing, Plone REST API only created tokens valid for the next 12 hours.
+
+In UNIX-like systems (OSX, Linux, Linux subsystem for Windows), a bash script would serve as a good way to retrieve the JWT from plone.restapi, by prompting for username and password:
+
+```bash
+bash
+read -p "Username: " USERNAME
+read -sp "Password: " PASSWORD
+curl -s -X POST http://localhost:8080/Plone/@login -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"login": "'"$USERNAME"'", "password": "'"$PASSWORD"'"}'
+exit
+```
+The above script will
+
+1. enter a new bash environment
+2. read username into environment variable
+3. read password into environment variable without displaying it when you type
+4. request authorization token
+5. exit bash to forget environment variables.
+
+This would give you a token as output:
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxsbmFtZSI6IkpvaG4gRG9lIiwic3ViIjoidXNlcm5hbWUiLCJleHAiOjE1Mjc0NDk0NTl9.epewKm09S6JXe07Ha6UNicN7v9MT32Rrkflxq2OqVRI"
+}
+```
+
+Install dotenv and setup `.env` with the token so that it can be used in the Gatsby project:
+
+```bash
+// Install dotenv
+yarn install dotenv
+
+
+// In .env in the project folder
+TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxsbmFtZSI6IkpvaG4gRG9lIiwic3ViIjoidXNlcm5hbWUiLCJleHAiOjE1Mjc0NDk0NTl9.epewKm09S6JXe07Ha6UNicN7v9MT32Rrkflxq2OqVRI
+```
+
+Finally setup `gatsby-config.js` to use this in your project:
+
+```javascript
+// Top of your file
+require("dotenv").config({
+  path: '.env',
+});
+
+// In plugins list
+module.exports = {
+  resolve: 'gatsby-source-plone',
+    options: {
+    baseUrl: 'http://localhost:8080/Plone/',
+    token: process.env.TOKEN,
+  }
+};
+```

docs/reference/expansions.md

@@ -0,0 +1,85 @@
+# Supported REST API expansions
+
+This source plugin only supports fixed set of Plone REST API expansions, currently *breadcrumbs* and *navigation*, which are both published as their own GraphQL nodes, *PloneBreadcrumbs* and *PloneNavigation* respectively.
+
+Expansions are [plone.restapi](https://plonerestapi.readthedocs.io/en/latest/expansion.html) mechanism to embed additional “components”, such as _navigation, breadcrumbs, schema,_ or _workflow_ within the main content response, helping the API consumers to avoid unnecessary requests.
+
+For instance, a normal GET request to `http://localhost:8080/Plone` would give the following response:
+
+```json
+{
+  "@components": {
+    "actions": {
+      "@id": "http://localhost:8080/Plone/@actions"
+    },
+    "breadcrumbs": {
+      "@id": "http://localhost:8080/Plone/@breadcrumbs"
+    },
+    "navigation": {
+      "@id": "http://localhost:8080/Plone/@navigation"
+    }
+  },
+  "@id": "http://localhost:8080/Plone",
+  "@type": "Plone Site",
+  "id": "Plone",
+  "...": "..."
+}
+```
+
+But in the case we need the _breadcrumbs, navigation_ data or so on, we'll need to make more requests to `/@breadcrumbs`, `/@navigation` and more depending on the data we need.
+
+Expansions simplifies this process by retrieving all data in a single request as `http://localhost:8080/Plone?expand=breadcrumbs,navigation` giving the response:
+
+```json
+{
+  "@components": {
+    "actions": {
+      "@id": "http://localhost:8080/Plone/@actions"
+    },
+    "breadcrumbs": {
+      "@id": "http://localhost:8080/Plone/@breadcrumbs",
+      "items": []
+    },
+    "navigation": {
+      "@id": "http://localhost:8080/Plone/@navigation",
+      "items": [
+        {
+          "@id": "http://localhost:8080/Plone",
+          "description": "",
+          "title": "Home"
+        },
+        {
+          "@id": "http://localhost:8080/Plone/news",
+          "description": "News on gatsby-source-plone development",
+          "title": "News"
+        },
+        {
+          "@id": "http://localhost:8080/Plone/index",
+          "description": "",
+          "title": "gatsby-source-plone"
+        },
+        {
+          "@id": "http://localhost:8080/Plone/search_traversal",
+          "description": "",
+          "title": "Traversal using @search endpoint"
+        },
+        {
+          "@id": "http://localhost:8080/Plone/plugin_options",
+          "description": "",
+          "title": "Plugin Options"
+        },
+        {
+          "@id": "http://localhost:8080/Plone/testcases",
+          "description": "A folder with different standard content types that Plone supports out of the box",
+          "title": "Testcases"
+        }
+      ]
+    }
+  },
+  "@id": "http://localhost:8080/Plone?expand=breadcrumbs%2Cnavigation",
+  "@type": "Plone Site",
+  "id": "Plone",
+  "is_folderish": true,
+  "...": "..."
+}
+```