docs: add new doc on why Gatsby uses GraphQL (#11787)

* docs: add new doc on why Gatsby uses GraphQL * docs: update docs/docs/why-gatsby-uses-graphql.md Co-Authored-By: jlengstorf <jason@lengstorf.com> * docs: update docs/docs/why-gatsby-uses-graphql.md Co-Authored-By: jlengstorf <jason@lengstorf.com> * docs: update docs/docs/why-gatsby-uses-graphql.md Co-Authored-By: jlengstorf <jason@lengstorf.com> * docs: update docs/docs/why-gatsby-uses-graphql.md Co-Authored-By: jlengstorf <jason@lengstorf.com> * docs: switch to npm and mention reserved props * docs: update description of data per @stefanprobst’s feedback * docs: embed egghead videos * fix: update video embed URLs * docs: update sidebar and add links * fix: trailing slash * fix: trailing slash * fix: trailing slash * fix: trailing slashes * fix: trailing slash
gatsbyjs · Mar 8, 2019 · b645b25 · b645b25
1 parent 6e57064
commit b645b25
Show file tree

Hide file tree

Showing 12 changed files with 422 additions and 2 deletions.
diff --git a/docs/docs/graphql-reference.md b/docs/docs/graphql-reference.md
@@ -8,6 +8,8 @@ This page will walk you through a series of GraphQL queries, each designed to de
 
 You'll be using GraphiQL, an interactive editor you can also use [while building your Gatsby site](/tutorial/part-five/#introducing-graphiql).
 
+For more information, read about [why Gatsby uses GraphQL](/docs/why-gatsby-uses-graphql/).
+
 ## Basic query
 
 Let's start with the basics, pulling up the site `title` from your `gatsby-config.js`'s `siteMetaData`. Here the query is on the left and the results are on the right.

diff --git a/docs/docs/graphql.md b/docs/docs/graphql.md
@@ -29,6 +29,6 @@ Which returns this:
 
 Notice how the query signature exactly matches the returned JSON signature. This is possible because in GraphQL, you query against a `schema` that is the representation of your available data. Don't worry about where the schema comes from right now, Gatsby takes care of organizing all of your data for you and making it discoverable with a tool called GraphiQL. GraphiQL is a UI that lets you 1) run queries against your data in the browser, and 2) dig into the structure of data available to you through a data type explorer.
 
-If you want to know more about what GraphQL is and why Gatsby uses it, check out this [conceptual guide](/docs/querying-with-graphql/) on querying data with GraphQL.
+If you want to know more about GraphQL, you can read more about [why Gatsby uses it](/docs/why-gatsby-uses-graphql/) and check out this [conceptual guide](/docs/querying-with-graphql/) on querying data with GraphQL.
 
 [[guidelist]]
diff --git a/docs/docs/images/why-gql-images.gif b/docs/docs/images/why-gql-images.gif
diff --git a/docs/docs/images/why-gql-no-data.png b/docs/docs/images/why-gql-no-data.png
diff --git a/docs/docs/images/why-gql-playground.png b/docs/docs/images/why-gql-playground.png
diff --git a/docs/docs/images/why-gql-product-json.png b/docs/docs/images/why-gql-product-json.png
diff --git a/docs/docs/images/why-gql-with-context.png b/docs/docs/images/why-gql-with-context.png
diff --git a/docs/docs/page-query.md b/docs/docs/page-query.md
@@ -6,6 +6,8 @@ Gatsby's `graphql` tag enables page components to retrieve data via GraphQL quer
 
 In this guide, you will learn [how to use the `graphql` tag](/docs/page-query#add-the-graphql-query) in your pages, as well as go a little deeper into [how the `graphql` tag works](/docs/page-query#how-does-the-graphql-tag-work).
 
+If you’re curious, you can also read more about [why Gatsby uses GraphQL](/docs/why-gatsby-uses-graphql/).
+
 ## How to use the `graphql` tag in pages
 
 ### Add `description` to `siteMetadata`

diff --git a/docs/docs/querying-with-graphql.md b/docs/docs/querying-with-graphql.md
@@ -21,6 +21,8 @@ the browser when needed by your components.
 
 ## Why is GraphQL so cool?
 
+For a more in-depth look, read [why Gatsby uses GraphQL](/docs/why-gatsby-uses-graphql/).
+
 - Eliminate frontend data boilerplate — no need to worry about requesting & waiting for data. Just ask for the data you need with a GraphQL query and it'll show up when you need it
 - Push frontend complexity into queries — many data transformations can be done at _build-time_ within your GraphQL queries
 - It's the perfect data querying language for the often complex/nested data dependencies of modern applications
@@ -336,6 +338,8 @@ export const query = graphql`
 
 ## Further reading
 
+- [Why Gatsby Uses GraphQL](/docs/why-gatsby-uses-graphql/)
+
 ### Getting started with GraphQL
 
 - http://graphql.org/learn/

diff --git a/docs/docs/using-gatsby-without-graphql.md b/docs/docs/using-gatsby-without-graphql.md
@@ -104,4 +104,5 @@ If you're building a small site, one efficient way to build it is to pull in uns
 
 ## Further reading
 
-Amberley Romo's guide to [using Gatsby without GraphQL](/blog/2018-10-25-using-gatsby-without-graphql/)
+- Amberley Romo's guide to [using Gatsby without GraphQL](/blog/2018-10-25-using-gatsby-without-graphql/)
+- [Why Gatsby Uses GraphQL](/docs/why-gatsby-uses-graphql/)