Merge branch 'master' into master

docs/docs/deploy-gatsby.md

@@ -178,7 +178,8 @@ or alternatively
 Uncaught Error: Minified React error #32; visit http://facebook.github.io/react/docs/error-decoder.html?invariant=32&args[]=## for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
 ```
 
-This is a new problem when dealing with static sites built with React. React
-uses HTML comments to help identify locations of components that do not render
-anything. If you are using a CDN that minifies your HTML, it will eliminate the
-HTML comments used by react to take control of the page on the client.
+This is a new problem when dealing with static sites built with React. This is
+not caused by Gatsby. React uses HTML comments to help identify locations
+of components that do not render anything. If you are using a CDN that minifies
+your HTML, it will eliminate the HTML comments used by React to take control of
+the page on the client. Cloudflare is a CDN that minifies HTML by default.

docs/docs/querying-with-graphql.md

@@ -2,23 +2,65 @@
 title: Querying with GraphQL
 ---
 
-Rough outline
-
-* What is GraphQL
-* Why GraphQL? As Gatsby runs on both server (at build time) & client, need way
-  to specify which data is needed.
-* Emphasize this is a _build-time only_ use of GraphQL. You don't need to run a
-  GraphQL server in production. Convenient way to describe data requirements of
-  component.
-* Why query colocation rocks.
-* Some basic terminology
-  * Types based on file type + way data can be transformed
-  * Connections
-  * Shallow intro to how data layer works e.g. source and transformer plugins.
-  * Compare to Webpack loaders — like loaders except create schema that can then
-    be queried.
-* Example queries showing off sorting, filtering, picking fields, programmatic
-  transformations
-* Link to some doc pages on advanced usages of GraphQL.
-* iFrame of graphiql instance for this site running on Heroku so people can run
-  live queries.
+> This page is a work in progress.
+
+# What is GraphQL?
+
+graphql.org describes it as "...a query language for APIs and a runtime for fulfilling those queries with your existing data".
+
+Gatsby uses GraphQL to create a consistent interface between your static site and your data sources, where data sources can be anything from local markdown files to a remote API.
+
+Gatsby describes your data by creating GraphQL _schemas_ from your data sources.
+
+GraphQL _queries_ can then be associated with your Gatsby pages, ensuring each page receives exactly the data it needs.
+
+
+# Why GraphQL?
+
+* As Gatsby runs on both server (at build time) & client,
+need way to specify which data is needed.
+* This is a *build-time only* use of GraphQL. You don't need to run a
+GraphQL server in production.
+* Convenient way to describe data requirements of component.
+* Why query colocation rocks
+* Uses the Relay Modern compiler behind the scenes
+
+# Basic Terminology
+
+* Types based on file type + way data can be transformed
+* Connections
+* Shallow intro to how data layer works e.g. source and transformer plugins.
+* Compare to webpack loaders — like loaders except create schema that
+can then be queried.
+* Named queries?
+* Using query parameters to manipulate results?
+
+# Example queries
+
+Showing off sorting, filtering, picking fields, programmatic transformations
+
+[Some example queries from Gatsby's tests](https://github.com/gatsbyjs/gatsby/blob/52e36b9994a86fc473cd2f966ab6b6f87ee8eedb/packages/gatsby/src/schema/__tests__/infer-graphql-input-type-test.js#L116-L432) - look for \`template literal blocks\` with `allNode{}` in them.
+
+...
+
+# Further reading
+
+## Getting started with GraphQL
+
+- http://graphql.org/learn/
+- https://services.github.com/on-demand/graphql/
+- https://apis.guru/graphql-voyager/
+- https://www.howtographql.com/
+- https://reactjs.org/blog/2015/05/01/graphql-introduction.html
+- ...
+
+## Advanced readings on GraphQL
+
+- [GraphQL specification](https://facebook.github.io/graphql/October2016/)
+- [Interfaces and Unions](https://medium.com/the-graphqlhub/graphql-tour-interfaces-and-unions-7dd5be35de0d)
+- [Gatsby uses the Relay Compiler](https://facebook.github.io/relay/docs/en/relay-compiler.html)
+- ...
+
+## TODO — create live GraphQL explorer for GatsbyJS.org
+
+* iFrame of graphiql instance for this site running on Heroku so people can run live queries.

packages/gatsby-image/README.md

@@ -8,6 +8,8 @@ Gatsby's GraphQL queries. It combines
 capabilities with advanced image loading techniques to easily and completely
 optimize image loading for your sites.
 
+*Warning: gatsby-image is **not** a drop-in replacement for `<img/>`. It's optimized for fixed width/height images and images that stretch the full-width of a container. Some ways you can use `<img/>` won't work with gatsby-image.*
+
 **[Demo](https://using-gatsby-image.gatsbyjs.org)**
 
 ## Problem

packages/gatsby-source-wordpress/README.md

@@ -16,9 +16,8 @@ An example site for this plugin is available.
 -   Should work with any number of article and post (tested on a site with 900
     posts)
 -   Can authenticate to wordpress.com's API using OAuth 2 so media can be queried
--   Easily create responsive images in Gatsby from WordPress images using
-    `gatsby-transformer-sharp` and `gatsby-plugin-sharp` in your
-    `gatsby-config.js`
+-   Easily create responsive images in Gatsby from WordPress images. See [image
+    processing](#image-processing) section.
 
 ## WordPress and custom entities
 
@@ -324,6 +323,81 @@ Mention the apparition of `childWordpressAcfField` in the query below :
   }
 ```
 
+### Image processing
+
+To use image processing you need `gatsby-transformer-sharp` and
+`gatsby-plugin-sharp` in your `gatsby-config.js`.
+
+You can apply image processing to:
+
+-   featured images (also known as post thumbnails),
+-   ACF fields:
+    -   Image field type (return value must be set to `Image Object` or `Image
+        URL` or field name must be `featured_media`),
+    -   Gallery field type.
+
+Image processing of inline images added in wordpress WYSIWIG editor is
+currently not supported.
+
+To access image processing in your queries you need to use this pattern:
+
+```
+imageFieldName {
+  localFile {
+    childImageSharp {
+      ...
+    }
+  }
+}
+```
+
+Full example:
+
+```graphql
+  allWordpressPost {
+    edges {
+      node {
+        title
+        featured_media {
+          localFile {
+            childImageSharp {
+              resolutions(width: 500, height: 300) {
+                ...GatsbyImageSharpResolutions_withWebp
+              }
+            }
+          }
+        }
+        acf {
+          image {
+            localFile {
+              childImageSharp {
+                sizes(maxWidth: 500) {
+                  ...GatsbyImageSharpSizes_withWebp
+                }
+              }
+            }
+          }
+          gallery {
+            localFile {
+              childImageSharp {
+                resize(width: 180, height: 180) {
+                  src
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+```
+
+To learn more about image processing check
+
+-   documentation of [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/),
+-   source code of [image processing example
+    site](https://github.com/gatsbyjs/gatsby/tree/master/examples/image-processing).
+
 ## Site's `gatsby-node.js` example
 
 ```javascript