docs(graphql): Update structure (#767)

* fix(docs): Fix structure for gitbook

* update doc

* rename yaml

* update snippet types

* remove duplicate intro

* fix changes

* put back upgrade

Author: joaogarin

.gitbook.yaml

@@ -0,0 +1 @@
+root: ./doc/

doc/...md README.mddoc/...md renamed to README.md

@@ -1,2 +1,65 @@
-# Introduction
+# Drupal GraphQL
+
+## Introduction
+
+The GraphQL Drupal module lets you query or mutate \(update/delete\) any content or configuration using the official GraphQL query language. This is an extremely powerful tool which opens the door for Drupal to be used in a multitude of applications.
+
+## Who is this module for?
+
+Anyone who wants to get JSON data out of Drupal.
+
+A few examples of where the GraphQL module could be used:
+
+* Decoupled Drupal applications with a javascript front-end \(React, Angular, Ember, etc\), 
+* Twig Templates \(Drupal theming\)
+* Mobile applications that need a persistent data store
+* IOT data storage
+
+## Hello World \(Quick Start\)
+
+1. Familiarize yourself with the GraphQL language. The official GraphQL docs are very well written. 
+
+   [http://graphql.org/learn/](http://graphql.org/learn/)
+
+2. Install the module and enable GraphQL, as well as GraphQL Core \(machine names are `graphql` and `graphql_core` respectively\).
+3. Login and navigate to `/graphql/explorer` \(Configuration > Web Services > GraphQL > Schemas > Explorer\)
+
+   This will bring you to the GraphiQL explorer.
+
+4. **Read the comments** and then enter the following query in the left pane:
+
+   ```graphql
+     query {
+       user: currentUserContext{
+         ...on User {
+           name
+         }
+       }
+     }
+   ```
+
+5. Press `Ctrl-Space` and you should see something like the following display in the right pane:
+
+   ```javascript
+    {
+      "data": {
+        "user": {
+            "name": "admin"
+      }
+    }
+   ```
+
+6. Congrats! You just figured out how to execute your first GraphQL query. This query is displaying the current logged in user, you.
+
+**NOTES:**
+
+* The GraphiQL explorer, included with the module, is your friend, it’s amazing. You will most likely use the GraphiQL explorer to build and test more complicated queries. 
+* GraphQL is introspective, meaning that the entire schema \(data model\) is known up front. This is important as it allows tools like GraphiQL to implement autocompletion. 
+* You can use GraphiQL to explore your way through the data and configuration, once you know the basic GraphQL syntax. You can use the tab key in the explorer like you would with autocompletion or intellisense in modern IDEs.
+* The `... User` in the query above is a fragment which exposes all of the fields on the User entity to us. Inline fragments like this can be a very powerful way to explore the schema. 
+
+**Resources**
+
+* [https://github.com/drupal-graphql/graphql](https://github.com/drupal-graphql/graphql)
+* [https://drupal.slack.com](https://drupal.slack.com) - The GraphQL Slack Channel is very active
 

doc/README.md

@@ -1,15 +1,12 @@
 # Table of contents
 
-* [Introduction](README.md)
-* [Introduction](...md)
-
 ## Getting started
 
-* [Getting started](getting-started/getting-started.md)
+* [Getting started](README.md)
 
 ## Queries
 
-* [Introduction](queries/queries.md)
+* [Queries](queries/README.md)
 * [Querying nodes](queries/querying-nodes.md)
 * [Querying taxonomies](queries/querying-taxonomies.md)
 * [Querying routes](queries/routes.md)
@@ -19,16 +16,16 @@
 
 ## Mutations
 
-* [Introduction](mutations/mutations.md)
+* [Mutations](mutations/README.md)
 * [Creating mutation plugins](mutations/creating-mutation-plugins.md)
 * [Writing custom mutations](mutations/custom-mutations.md)
 * [Writing custom validations](mutations/custom-validations.md)
 
 ## Authentication
 
-* [Introduction](authentication/introduction.md)
+* [Authentication](authentication/README.md)
 
 ## Metatag / SEO
 
-* [Metatag support](metatag-seo/metatag.md)
+* [Metatag](metatag-seo/README.md)
 

doc/SUMMARY.md

@@ -0,0 +1,31 @@
+# Authentication
+
+When it comes to authentication the Drupal GraphQL module is very much independent of what kind of authentication system or technique you use, as long as in the end you are able to send a token via the `Authorization` header.
+
+Drupal has some modules for doing decoupled authentiation using tokens :
+
+* [Simple oauth](https://www.drupal.org/project/simple_oauth)
+* [JWT](https://www.drupal.org/project/jwt)
+
+## Bearer token
+
+To authenticated a graphql request with Drupal you need to attach the token you get with those modules as a `Bearer` in the Authorization header. Here is how that can look like when doing a fetch call :
+
+```javascript
+...
+fetch(url, {
+  method: 'post',
+  headers: {
+    'Authorization': `Bearer ${token}`
+  },
+  body: '...'
+})
+  .then(json)
+  ...
+```
+
+Once a request goes with that token the user will be authenticated and Drupal's permission system and access checking will work using that user.
+
+## Basic auth
+
+Most recently Drupal's own Basic auth module support was also added so you can aslo use that to authenticated queries to drupal.

doc/authentication/README.md

@@ -1,12 +1,12 @@
-# Metatag support
+# Metatags
 
 ## Metatag
 
 The easiest way to use the Metatag module together with GraphQL is to use the [GraphQL Metatag](https://www.drupal.org/project/graphql_metatag) module. It comes with built-in support for using metatags with GraphQL.
 
 ## Metatag Queries
 
-```text
+```graphql
 {
   nodeById(id: "1") {
     entityId
@@ -23,7 +23,7 @@ The easiest way to use the Metatag module together with GraphQL is to use the [G
 
 This will give you something like this as a response :
 
-```text
+```json
 {
   "data": {
     "nodeById": {
@@ -37,7 +37,7 @@ This will give you something like this as a response :
           "key": "canonical",
           "value": "https://websiteurl.com/node/1"
         }
-      ],
+      ]
     }
   }
 }
@@ -47,7 +47,7 @@ This way you can easily manipulate SEO information in the Node in Drupal but sti
 
 You can of course use this in any kind of query that would return the entity that holds the metatag information. As an example querying a route and getting from that entity the metatag information would look something like this :
 
-```text
+```graphql
 {
   route(path: "/article-name") {
     ... on EntityCanonicalUrl {
@@ -65,7 +65,7 @@ You can of course use this in any kind of query that would return the entity tha
 
 This would return any information on this particular route, including the meta information requested.
 
-```text
+```json
 {
   "data": {
     "route": {
@@ -95,9 +95,9 @@ There is a currently an [issue](https://github.com/drupal-graphql/graphql/issues
 
 _"If a module \(e.g. metatag\) introduces a new primitive data type, it is not part of the derived types, but any field using it will reference it. That results in a "Missing type metatag." exception."_
 
-So for now you need to include a custom Scalar as a workaround to avoid errors in GraphQL due to this missing type. Create a file inside a custom module of your own, named for example "MetatagScalar.php" where a custom scalar will be defined. In this example the module's name is graphql\_custom as seen from the namespace bellow. Make sure to not conflict with existing namespaces when defining it.
+So for now you need to include a custom Scalar as a workaround to avoid errors in GraphQL due to this missing type. Create a file inside a custom module of your own, named for example "MetatagScalar.php" where a custom scalar will be defined. In this example the module's name is graphql_custom as seen from the namespace bellow. Make sure to not conflict with existing namespaces when defining it.
 
-```text
+```php
 <?php
 
 namespace Drupal\graphql_custom\Plugin\GraphQL\Scalars;
@@ -120,4 +120,3 @@ class MetatagScalar extends StringScalar {
 
 }
 ```
-

doc/authentication/introduction.md

@@ -1,4 +1,4 @@
-# Introduction
+# Mutations
 
 In GraphQL, a mutation is the terminology used whenever you want to add, modify, or delete data stored on the server, in this case Drupal.
 
@@ -13,15 +13,15 @@ The corresponding example code for creating, deleting, updating, and fileuploads
 A simple mutation to add an article content type \(node entity / article bundle\) might look the following:
 
 ```graphql
-mutation{
-  addArticle(input: {title: "Hey"}){
+mutation {
+  addArticle(input: { title: "Hey" }) {
     errors
     violations {
       message
       code
       path
-    },
-    article: entity{
+    }
+    article: entity {
       ... on NodeArticle {
         nid
       }
@@ -36,7 +36,7 @@ In the mutation above, we use the inline fragment `... on NodeArticle { nid } to
 
 The result of the above mutation would look something like this:
 
-```javascript
+```json
 {
   "data": {
     "addArticle": {
@@ -54,4 +54,3 @@ External Resources:
 
 * [http://graphql.org/learn/queries/\#mutations](http://graphql.org/learn/queries/#mutations)
 * [https://www.amazeelabs.com/en/blog/extending-graphql-part-3-mutations](https://www.amazeelabs.com/en/blog/extending-graphql-part-3-mutations)
-

doc/getting-started/getting-started.md

@@ -18,7 +18,7 @@ The first step to create a mutation is to make the plugin. The graphql module pr
 
 Let's look at what the code for this plugin looks like :
 
-```text
+```php
 <?php
 
 namespace Drupal\graphql_examples\Plugin\GraphQL\Mutations;
@@ -92,7 +92,7 @@ We can see we are assigning the `title` that we are passing in the input \(we wi
 
 Let's continue with our article example. In this case we implement a mutation to update a given article. Because we are updating a particular entity and we need to know which entity it is, we will need to provide the plugin annotation with something extra, an Id for the entity.
 
-```text
+```php
 <?php
 
 namespace Drupal\graphql_examples\Plugin\GraphQL\Mutations;
@@ -143,7 +143,7 @@ The first thing we noticed is we are now using `UpdateEntityBase` instead of "Cr
 
 The only thing left now is really to delete the entity right? This is the simplest type of operation out of the 3, because we only need to give graphql the `id`, it will check if we can access that type of operation and if so delete the entity with the id we give to it. So let's look at how the plugin looks like
 
-```text
+```php
 <?php
 
 namespace Drupal\graphql_examples\Plugin\GraphQL\Mutations;
@@ -174,7 +174,7 @@ We extend the `DeleteEntityBase` class and only require one argument: the id of
 
 We know from the examples above that we need to define the arguments for mutations. Similar to how a function, mutations receive arguments that can be used to do whatever the mutation needs to do to work. In order for graphql to know information about the arguments we create an `InputType`. The ArticleInput that we used above looks like this :
 
-```text
+```php
 <?php
 
 namespace Drupal\graphql_examples\Plugin\GraphQL\InputTypes;
@@ -202,4 +202,3 @@ class ArticleInput extends InputTypePluginBase {
 We can see again that we namespace this plugin to our module name, in this case `graphql_examples` should be replaced by your own module name. This file should live inside `{{module_name}}/src/Plugin/GraphQL/InputTypes/ArticleInput.php`
 
 We can also see above that we only use annotations here to define the arguments inside the `fields` property. So we know that it receives a `title` and that's a "String" and we also receive a `body` which is also a `String`.
-