[v2] docs - update page query docs

docs/docs/build-a-page-with-graphql-query.md → docs/docs/page-query.md

@@ -1,12 +1,14 @@
 ---
-title: Build a page with a GraphQL query
+title: Querying data in pages with graphql
 ---
 
-Gatsby creates pages from components located within `src/pages`. It watches the folder and will create and remove pages as you add and remove components. The pathname for each page is derived from the name of the component. For example, `src/pages/about.js` would be located at `/about/` when published.
+Gatsby's `graphql` tag enables page components to retrieve data via GraphQL query.
 
-In this guide, you will learn how to perform a query of your site's metadata for the description to display on your homepage.
+In this guide, you will learn [how to use the `graphql` tag](/page-query#adding-the-graphql-query) in your pages, as well as go a little deeper into [how the `graphql` tag works](/page-query#how-does-the-graphql-tag-work).
 
-## Adding `description` to `siteMetadata`
+## How to use the `graphql` tag in pages
+
+### Add `description` to `siteMetadata`
 
 The first step in displaying the description will be ensuring you have one to begin with.
 
@@ -21,7 +23,7 @@ module.exports = {
 }
 ```
 
-## Basic Index Page Markup
+### Mark up basic index page
 
 A simple index page (`src/pages/index.js`) can be marked up like so:
 
@@ -35,9 +37,9 @@ const HomePage = () => {
 export default HomePage
 ```
 
-## Adding the GraphQL Query
+### Add the `graphql` query
 
-The first thing to do is import GraphQL from Gatsby. At the top of `index.js` add:
+The first thing to do is import `graphql` from Gatsby. At the top of `index.js` add:
 
 ```diff
 import React from 'react'
@@ -87,7 +89,7 @@ export const query = graphql`
 `
 ```
 
-## Get Data into the `<HomePage />` Component
+### Provide data to the `<HomePage />` component
 
 To start, update the `HomePage` component to destructure `data` from props.
 
@@ -121,3 +123,18 @@ export default HomePage
 ```
 
 After restarting `gatsby develop`, your home page will now display "This is where I write my thoughts." from the description set in `gatsby-config.js`!
+
+## How does the graphql tag work?
+
+`graphql` is a [tag function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals). Behind the scenes Gatsby handles these tags in a particular way:
+
+### The short answer
+
+During the Gatsby build process, GraphQL queries are pulled out of the original source for parsing.
+
+### The longer answer
+
+The longer answer is a little more involved: Gatsby borrows a technique from
+[Relay](https://facebook.github.io/relay/) that converts your source code into an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) during the build step. [`file-parser.js`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/internal-plugins/query-runner/file-parser.js) and [`query-compiler.js`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/internal-plugins/query-runner/query-compiler.js) pick out your `graphql`-tagged templates and effectively remove them from the original source code.
+
+This means that the `graphql` tag isn’t executed the way that you might expect. For example, you cannot use [expression interpolation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Expression_interpolation) with Gatsby's `graphql` tag.

docs/docs/static-query.md

@@ -1,10 +1,14 @@
 ---
-title: "Querying data in components using StaticQuery"
+title: Querying data in components using StaticQuery
 ---
 
 Gatsby v2 introduces `StaticQuery`, a new API that allows components to retrieve data via GraphQL query.
 
-## Basic example
+In this guide, we'll walk through an example using `StaticQuery`, and discuss [the difference between a StaticQuery and a page query](/static-query/#how-staticquery-differs-from-page-query).
+
+## How to use `StaticQuery` in components
+
+### Basic example
 
 We'll create a new `Header` component located at `src/components/header.js`:
 
@@ -36,7 +40,7 @@ export default Header
 
 Using `StaticQuery`, you can colocate a component with its data. No longer is it required to, say, pass data down from `Layout` to `Header`.
 
-## Typechecking
+### Typechecking
 
 With the above pattern, you lose the ability to typecheck with PropTypes. To regain typechecking while achieving the same result, you can change the component to:
 

docs/tutorial/part-four/index.md

@@ -229,7 +229,7 @@ Restart the development server.
 
 ### Use a page query
 
-Now the site title is available to be queried; Let's add it to the `about.js` file using a page query:
+Now the site title is available to be queried; Let's add it to the `about.js` file using a [page query](/docs/page-query):
 
 ```jsx{2,5,7,14-23}
 import React from "react"
@@ -348,22 +348,6 @@ So almost everywhere, changes you make will immediately take effect. Edit the `g
 
 ![Both titles say Pandas Eating Lots](/pandas-eating-lots-titles.png)
 
-## How does the graphql tag work?
-
-You may have noticed that you used a [tag function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals) called `graphql`. Behind the scenes Gatsby handles these tags in a particular way - let's take a deeper look at what actually happens when you use Gatsby's `graphql` tag:
-
-### The short answer
-
-During the Gatsby build process, GraphQL queries are pulled out of the original source for parsing.
-
-### The longer answer
-
-The longer answer is a little more involved: Gatsby borrows a technique from
-[Relay](https://facebook.github.io/relay/) that converts your source code into an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) during the build step. [`file-parser.js`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/internal-plugins/query-runner/file-parser.js) and [`query-compiler.js`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/internal-plugins/query-runner/query-compiler.js) pick out your `graphql`-tagged templates and effectively remove them from the original source code.
-
-This means that the `graphql` tag isn’t executed the way that you might expect. For example, you cannot use [expression interpolation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Expression_interpolation) with Gatsby's `graphql` tag.
-
-
 ## What's coming next?
 
 Next, you'll be learning about how to pull data into your Gatsby site using

www/src/data/sidebars/doc-links.yaml

@@ -93,10 +93,12 @@
       items:
         - title: Introducing GraphiQL*
           link: /docs/introducing-graphiql/
-        - title: Build a page with a GraphQL query
-          link: /docs/build-a-page-with-graphql-query/
         - title: Creating and modifying pages
           link: /docs/creating-and-modifying-pages/
+        - title: Querying data in pages with graphql
+          link: /docs/page-query/
+        - title: Querying data in components with StaticQuery
+          link: /docs/static-query/
         - title: Adding Markdown pages
           link: /docs/adding-markdown-pages/
         - title: Adding a list of Markdown blog posts
@@ -105,8 +107,6 @@
           link: /docs/creating-slugs-for-pages/
         - title: Programmatically create pages from data*
           link: /docs/programmatically-create-pages-from-data/
-        - title: Querying data with StaticQuery
-          link: /docs/static-query/
     - title: Plugins
       link: /docs/plugins/
       items: