Merge pull request #1 from gatsbyjs/master

Update fork

docs/blog/2018-06-08-life-after-layouts/index.md

@@ -83,7 +83,7 @@ In short, the decision to remove layouts was part of an effort to reduce unneces
 
 ### What was the unnecessary complexity?
 
-Because layouts in V1 were applied under the hood, it made it _really hard_ to pass data between the layout the pages it wrapped.
+Because layouts in V1 were applied under the hood, it made it _really hard_ to pass data between the layout and the pages it wrapped.
 
 In short, layouts in V1 broke React's compositional model, and that made things unnecessarily hard to implement. By going back to the standard React way of importing components and using them directly, we're able to easily pass data between the layout and pages without any confusing, complicated, or otherwise unwieldy workarounds.
 
@@ -93,7 +93,7 @@ In V1, if something breaks on your page, you'd likely go to the page, look throu
 
 Because Gatsby is doing things in the background, out of sight of the developers building the site, we're creating a mystery: where the hell did this bug come from if all the code I can see doesn't have the bug?
 
-By removing the magic and making layouts an explicity dependency in V2, that same bug would be much easier to spot because there's a clear link between our page code and the layout.
+By removing the magic and making layouts an explicit dependency in V2, that same bug would be much easier to spot because there's a clear link between our page code and the layout.
 
 ### Why is this better?
 

docs/blog/2018-06-18-moving-from-create-react-app-to-gatsby-js/index.md

@@ -22,7 +22,7 @@ If you came across [Gatsby](https://github.com/gatsbyjs/gatsby) you will notice
 
 ![gatsby-logo](https://images.ctfassets.net/4x6byznv2pet/4OW1X9ex1mImko8G4w4WAK/a16fceab310b718c7f375a760c4e1e16/logo-gatsby-0603eb9dd6bdfec9599dbc7590f891be-347ea.jpg)
 
-Gatsby is a blazing fast static site generator for [React](https://github.com/facebook/react). Actually, it is more than that. Think of it as a PWA (Progressive Web App) framework with best practices backed in. For example: you get code and data splitting out-of-the-box.
+Gatsby is a blazing fast static site generator for [React](https://github.com/facebook/react). Actually, it is more than that. Think of it as a PWA (Progressive Web App) framework with best practices baked in. For example: you get code and data splitting out-of-the-box.
 
 ## Why Move to Gatsby?
 

docs/blog/2018-06-24-investigating-gatsby-build-performance-at-scale/index.md

@@ -0,0 +1,55 @@
+---
+title: Investigating Build Performance At Scale
+date: "2018-06-24"
+author: "Sam Bhagwat"
+tags: ["scalability", "builds"]
+---
+When website teams are deciding whether to migrate an existing site over to Gatsby, one consideration is how long it takes to rebuild each site when code or content changes.
+
+In order to help teams evaluate this, we’re publishing a set of build time benchmarks.
+
+# Performance Considerations
+
+Generally speaking, Gatsby build times consist of two factors -- O(1) constant-time operations, such as connecting to remote APIs, and O(n) linear-time operations, such as processing markdown pages, transforming images, and so on.
+
+On smaller sites, O(1) constant time operations take up most of the time “cost” of building a Gatsby site. On larger sites, O(n) linear-time operations predominate. Generally, larger sites tend to be CPU-bound rather than I/O-bound, so a more powerful server, VM, or container will finish quicker.
+
+The three most memory-intensive operations that scale with site size are **processing markdown**, **creating pages**, and **processing images with gatsby-image**.
+
+# Benchmark Parameters
+
+_Site tests_
+
+In order to measure the “build performance cost” of each of these three factors, we’ve benchmarked Gatsby build times for two different sites, one image-heavy and one markdown-page heavy.
+
+The first site is [FreeCodeCamp’s Guide](https://github.com/freeCodeCamp/guide), one of the largest open-source Gatsby sites with around 3,000 pages. The second site is the using-gatsby-image official example [copied into its own repo](https://github.com/calcsam/gatsby-image-performance-benchmarking). We’ve run two different versions of this: first, with around 25 images and second, with around 250 images. Both sites are running on Gatsby v2.
+
+Note that **using gatsby-image is not a requirement to use Gatsby**. If you have enough images that image-processing-driven build times is impeding project goals or team workflows, consider simply removing (or not implementing) gatsby-image.
+
+_Machine types_
+
+Tests were run on three different machines; on a local development machine (2015 Macbook Pro), on an AWS t2 micro free tier instance, and an AWS memory-optimized m4 instance.
+
+_Cold start vs warm start_
+
+Tests were run both with (“warm start) and without (“cold start”) a pre-existing, local Gatsby cache.
+
+In most cases when code changes and all cases when content changes, Gatsby will preserve the cache from your previous build, giving you a warm start. The cache is only invalidated in rare instances, for example when the plugin changes.
+
+Whether you’re able to access the cache from previous builds depends on your CI setup, but many CI providers offer the option of preserving the previous build cache.
+
+# Results
+
+For cold start builds, each additional markdown page adds around **0.17 seconds**, while each additional image processed with gatsby-image adds **between 1.5 and 2.1 seconds** to fresh Gatsby builds.
+
+For warm start builds, each additional markdown page adds **around 0.07 seconds**, while additional images processed with gatsby-image are free.
+
+Full results are [linked](https://docs.google.com/spreadsheets/d/1ki5PwVTnIyycsk800DSWIA72UAr1k1DUJnKCf_lWz4c/edit#gid=0), along with our [build script](https://gist.github.com/calcsam/4aa066a46d74b6713c053a6adc0e0f76).
+
+# Next steps
+
+Gatsby users report that Gatsby builds fail due to running against hard Node.js process memory limits somewhere around 10,000 to 15,000 pages on v1.
+
+Since v2 has improved memory usage, we want to update this number, as well as further quantify the boundary so that teams considering migrating larger sites to Gatsby have more information for their decision-making.
+
+We also want to benchmark v2 build performance against v1 build performance for various sites.

docs/blog/2018-06-26-card-sort-results/index.md

@@ -0,0 +1,107 @@
+---
+title: Presenting the Docs Redesign Card Sort Results
+date: 2018-06-26
+author: Shannon Soper
+tags: ["documentation"]
+---
+
+## What is a card sort?
+
+Recently, 36 Gatsby users completed an open card sort to help make our docs here on gatsbyjs.org easier to use. Without any outside input or help, they each sorted 90 cards into categories that made sense to them and then named those categories.
+
+### Raw & beautified data
+
+I ran this card sort through [OptimalSort](https://www.optimalworkshop.com/), a software that moderates the card sort and presents the data in usable forms. If you’re curious to see the full results, you can [view the data](https://www.optimalworkshop.com/optimalsort/x87kpp82/5x34psa3-0/shared-results/fa8b66knb66qyhwh5l8j38bd273vkkm7), including raw data as well as things like a similarity matrix and a [dendogram](https://support.optimalworkshop.com/hc/en-us/articles/201997650-Interpreting-the-OptimalSort-dendrograms).
+
+## How did participants categorize the docs?
+
+People sorted the docs into the following categories:
+* Get Started / Welcome to Gatsby / Intro
+* Development environment
+* Releases & Migration
+* Core Concepts / About Gatsby
+* Advanced Guides
+* API Reference
+* Tutorials / Examples
+* Contributing
+
+These categories weren’t too surprising (I included multiple names when the some category names were equally popular). However, upon further digging into the data, I discovered some unexpected results that further refine how we might categorize the docs, write new docs, and change how we think and talk about Gatsby.
+
+## PWA
+
+No one seems to know what to do with the doc titled “Building apps with Gatsby”. In the similarity matrix data visualization, 41% of people associated it with the “Authentication tutorial” doc and 41% also associated it with the “Progressive web app” doc. A 41% isn’t *very* strong. Essentially, this means participants didn’t think it “fit” very snugly alongside any other docs. 
+
+![Building apps with Gatsby is weakly associated with other docs](building-apps-with-gatsby.png)
+
+This could mean several things:
+1. We don’t have very many docs about how Gatsby can be used to build dynamic apps
+2. People don’t think of Gatsby as a tool they’d use to build apps with
+3. The title of the doc is too broad or too vague
+
+Without interviewing each participant I can’t be sure, but I’m inclined to think a combination of all three factors means people don’t know where to put that doc in the navigation. This might mean we need clarity in how we present what Gatsby *is* in all our informational material and marketing and that we build more docs about Gatsby being more than a static site generator.
+
+### Deployment
+
+There was a lot of disagreement about where docs about deployment should go. For example, card sort participants placed the “Build and deploy a live site” doc in 28 unique categories. Here’s a sample of the categories:
+
+![Deployment categories](deployment-categories.png)
+
+The three most common categories it was placed under are “Getting Started”, “Tutorials,” and “Deployment.” Other categories include “Examples,” “Guides,” and “Production.” Here are the deployment docs that need to find a place to call home:
+* Build and deploy a site
+* Preparing site for deployment
+* Deploying a site live online
+
+One solution that occurred to me is to bring Deployment & Hosting to top level navigation as their own category, since there was so little agreement on where to put them.
+
+> ***NOTE:*** If you look at the data, the number of unique categorizations isn’t always a useful number, because Optimal Sort considers “getting started” and “get started” to be different categories even though a human eye can see they are essentially the same. However, in the case of these deployment docs, there were 28 categories and many of them are *truly unique*.
+
+### Core Concepts vs. Advanced Guides
+
+There was quite a bit of overlap in the docs people assigned to these two categories. This is probably because the two categories have a close relationship with each other; they work in harmony to help Gatsby users build at an advanced level. For example, if you read about how Gatsby works with GraphQL in “Core Concepts,” there is a high chance you’ll want to start playing with GraphQL queries and find examples of these in “Advanced Guides.” I’m not entirely sure how to reflect this close relationship in the docs; the most straightforward way is probably for each doc in “Core Concepts” to have a list of relevant links in "Advanced Guides," and vice versa.
+
+Here’s a sampling of docs that people associate with both categories:
+* Search engine optimization (SEO) 
+* Authentication
+* E-commerce
+
+List of other lonely docs that didn’t find a solid home through the card sort:
+* The “RFC Process” doc didn’t find a snug fit. Two people didn’t know what it meant, and 44% of people put it under Contributing, but that’s not a majority. Seems like many people don’t know where to put it. I’m wondering if the title is too vague.
+* There was little agreement on where the “Html.js” doc goes. There was a 47% association with Babel and a 47% association with using layouts to build reusable site sections.
+* “React components” highest association was a 47% association with “basic structure of a Gatsby site” and all its associated pages. This slightly low association score probably results from the fact that the .org site doesn’t teach that much React at all, and there aren’t many docs on React specifically.
+
+## Dendogram adventures
+
+These screenshots that show a portion of the dendogram show that the clearest category was "Contributing", clear because the category name and the contents of the category are consistent:
+
+![Contributing dendogram](contributing-dendogram.png)
+
+Gatsby users are in agreement on what that category ought to be called and what docs it should contain :)
+
+## Next steps
+
+### Usability testing
+
+The next step is to conduct usability testing on a new design of the .org site. I’ve already conducted 8 usability tests with several more coming (5-7 produces reliable data in conventional UX research practices) and I’m seeing more ways to improve what we place in these categories as well as many ways I can improve my usability testing :). 
+
+Many thanks to all those participants who have been enthusiastic and willing to give feedback, including Korey Boone, Shannon Smith, Peter Wiebe, Abhishek Vishwakarma, Ria Carmin, and Hugo Marques, Bogdan Lazar, Cameron Steele, and Simon Koelewijn. There are quite a few more people meeting with me in the upcoming week.
+
+These are the docs categories I’ve used for usability testing so far:
+* Get Started
+* Core Concepts
+* Releases
+* API Reference
+* Recipes
+* Tutorials
+* Contributing
+
+Here are a few realizations from usability testing already: 
+* sometimes people don’t see the search bar on the .org site
+* when searching for something in the docs or to solve an error, many people do a google search before using docs navigation or the .org search bar
+* the category name “Recipes” was unclear to most people, although once they see the contents of the category, most people tend to like it 
+* the usability testing validated one of the card sort results, which is that some docs kind of fit in three categories: "Core Concepts" and "Recipes" and "Tutorials". These categories are all closely related and will need to link to each other often
+
+### What’s next
+
+Stay tuned for the results of the usability test and the new sidebar menu of the .org site, which will likely get released together :D 
+
+And please read and comment on the [Doc Redesign RFC](https://github.com/gatsbyjs/rfcs/pull/5) if you have more ideas on how we can redesign the docs!

docs/docs/graphql-reference.md

@@ -76,6 +76,14 @@ To add variables to page component queries, pass these in the `context` object [
 
 <iframe src="https://gatsbygraphql.sloppy.zone/?query=query%20GetBlogPosts(%24limit%3A%20Int%2C%20%24filter%3A%20filterMarkdownRemark%2C%20%24sort%3A%20markdownRemarkConnectionSort)%20%7B%0A%09allMarkdownRemark(%0A%20%20%20%20limit%3A%20%24limit%2C%0A%20%20%20%20filter%3A%20%24filter%2C%0A%20%20%20%20sort%3A%20%24sort%0A%20%20)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20fields%7B%0A%20%20%20%20%20%20%20%20%20%20slug%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20frontmatter%20%7B%0A%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%20%20date(formatString%3A%20%22dddd%20DD%20MMMM%20YYYY%22)%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%20%20%20%20%0A%7D&operationName=GetBlogPosts&variables=%7B%0A%20%20%22limit%22%3A%203%2C%0A%20%20%22filter%22%3A%20%7B%0A%20%20%20%20%22frontmatter%22%3A%20%7B%0A%20%20%20%20%20%20%22date%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%22ne%22%3A%20null%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%2C%0A%20%20%22sort%22%3A%20%7B%0A%20%20%20%20%22fields%22%3A%20%22frontmatter___date%22%2C%0A%20%20%20%20%22order%22%3A%20%22DESC%22%0A%20%20%7D%0A%7D" width="600" height="400"></iframe>
 
+## Group
+
+You can also group values on the basis of a field e.g. the title, date or category and get the field value, the total number of occurences and edges.
+
+The query below gets us all authors (`fieldValue`) who wrote a blogpost and how many blogposts (`totalCount`) they wrote. In addition we're grabbing the `title` and `slug` of the author's articles.
+
+<iframe src="https://gatsbygraphql.sloppy.zone/?query=%7B%0A%20%20allMarkdownRemark(filter%3A%20%7BfileAbsolutePath%3A%20%7Bregex%3A%20%22%2Fdocs.blog%2F%22%7D%7D)%20%7B%0A%20%20%20%20group(field%3A%20frontmatter___author)%20%7B%0A%20%20%20%20%20%20fieldValue%0A%20%20%20%20%20%20totalCount%0A%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20fields%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20slug%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20frontmatter%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D" width="600" height="400"></iframe>
+
 ## Where next?
 
 Try [running your own queries](<https://gatsbygraphql.sloppy.zone/?query=%23%20Welcome%20to%20GraphiQL%0A%23%0A%23%20GraphiQL%20is%20an%20in-browser%20tool%20for%20writing%2C%20validating%2C%20and%0A%23%20testing%20GraphQL%20queries.%0A%23%0A%23%20Type%20queries%20into%20this%20side%20of%20the%20screen%2C%20and%20you%20will%20see%20intelligent%0A%23%20typeaheads%20aware%20of%20the%20current%20GraphQL%20type%20schema%20and%20live%20syntax%20and%0A%23%20validation%20errors%20highlighted%20within%20the%20text.%0A%23%0A%23%20GraphQL%20queries%20typically%20start%20with%20a%20%22%7B%22%20character.%20Lines%20that%20starts%0A%23%20with%20a%20%23%20are%20ignored.%0A%23%0A%23%20All%20the%20data%20behind%20gatsbyjs.org%20can%20be%20queried%20from%20here.%20Below%20is%20%0A%23%20an%20example%20query%20to%20get%20you%20started.%0A%23%0A%23%20Keyboard%20shortcuts%3A%0A%23%0A%23%20%20Prettify%20Query%3A%20%20Shift-Ctrl-P%20(or%20press%20the%20prettify%20button%20above)%0A%23%0A%23%20%20%20%20%20%20%20Run%20Query%3A%20%20Ctrl-Enter%20(or%20press%20the%20play%20button%20above)%0A%23%0A%23%20%20%20Auto%20Complete%3A%20%20Ctrl-Space%20(or%20just%20start%20typing)%0A%23%0A%0A%7B%0A%20%20allSitePage(%0A%20%20%20%20limit%3A%205%0A%20%20)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20path%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D>), check out the rest of [the docs](/docs/) or run through [the tutorial](/tutorial/).

docs/docs/migrating-from-v1-to-v2.md

@@ -58,6 +58,7 @@ Read on for a detailed guide on what's new in version 2!
 - [Only allow defined keys on node.internal object](#only-allow-defined-keys-on-the-node-internal-object)
 - [Import `graphql` types from `gatsby/graphql`](#import-graphql-types-from-gatsbygraphql)
 - [Move Babel Configuration`](#move-babel-configuration)
+- [Plugin specific changes](#plugin-specific-changes)
 
 You can start with a few of the most important steps - install Gatsby v2 dependencies and update your layout components.
 
@@ -503,3 +504,19 @@ The latest version of Gatsby uses Babel 7, which introduced [a new behavior for
 [This GitHub comment](https://github.com/facebook/jest/issues/1468#issuecomment-361260279) documents the steps needed to do that.
 
 More information on Gatsby and Babel configuration available [here](/docs/babel/#how-to-use-a-custom-babelrc-file).
+
+## Plugin specific changes
+
+Some plugins require additional changes before your site will compile.
+For example, if you use [`gatsby-plugin-typography`](https://www.gatsbyjs.org/packages/gatsby-plugin-typography/), you now need to explicitly export `scale` and `rhythm` as named exports from your typography config module.
+
+`src/utils/typography.js`
+
+```diff
+- const typography = new Typography();
+- export default typography;
+
++ const typography = new Typography();
++ const { rhythm, scale } = typography;
++ export { rhythm, scale, typography as default };
+```

docs/docs/node-interface.md

@@ -16,7 +16,7 @@ fields: Object,
 internal: {
   contentDigest: String,
   // Optional media type (https://en.wikipedia.org/wiki/Media_type) to indicate
-  // to transformer plugins this node has data they can futher process.
+  // to transformer plugins this node has data they can further process.
   mediaType: String,
   // A globally unique node type chosen by the plugin owner.
   type: String,