Merge branch 'master' into master

benchmarks/markdown_id/content/blog/hello-world/index.md

@@ -9,7 +9,7 @@ This is my first post on my new fake blog! How exciting!
 I'm sure I'll write a lot more interesting things in the future.
 
 Oh, and here's a great quote from this Wikipedia on
-[salted duck eggs](http://en.wikipedia.org/wiki/Salted_duck_egg).
+[salted duck eggs](https://en.wikipedia.org/wiki/Salted_duck_egg).
 
 > A salted duck egg is a Chinese preserved food product made by soaking duck
 > eggs in brine, or packing each egg in damp, salted charcoal. In Asian

benchmarks/markdown_id/content/blog/my-second-post/index.md

@@ -8,6 +8,6 @@ Wow! I love blogging so much already.
 Did you know that "despite its name, salted duck eggs can also be made from
 chicken eggs, though the taste and texture will be somewhat different, and the
 egg yolk will be less rich."?
-([Wikipedia Link](http://en.wikipedia.org/wiki/Salted_duck_egg))
+([Wikipedia Link](https://en.wikipedia.org/wiki/Salted_duck_egg))
 
 Yeah, I didn't either.

benchmarks/markdown_slug/content/blog/hello-world/index.md

@@ -9,7 +9,7 @@ This is my first post on my new fake blog! How exciting!
 I'm sure I'll write a lot more interesting things in the future.
 
 Oh, and here's a great quote from this Wikipedia on
-[salted duck eggs](http://en.wikipedia.org/wiki/Salted_duck_egg).
+[salted duck eggs](https://en.wikipedia.org/wiki/Salted_duck_egg).
 
 > A salted duck egg is a Chinese preserved food product made by soaking duck
 > eggs in brine, or packing each egg in damp, salted charcoal. In Asian

benchmarks/markdown_slug/content/blog/my-second-post/index.md

@@ -8,6 +8,6 @@ Wow! I love blogging so much already.
 Did you know that "despite its name, salted duck eggs can also be made from
 chicken eggs, though the taste and texture will be somewhat different, and the
 egg yolk will be less rich."?
-([Wikipedia Link](http://en.wikipedia.org/wiki/Salted_duck_egg))
+([Wikipedia Link](https://en.wikipedia.org/wiki/Salted_duck_egg))
 
 Yeah, I didn't either.

docs/blog/100days/apps/index.md

@@ -0,0 +1,43 @@
+---
+title: Challenge 12 - Transform Your Gatsby Website into a Web App
+date: 2020-03-18
+author: "Hashim Warren"
+excerpt: "Learn how to add dynamic features to your Gatsby site"
+tags: ["learning-to-code", "100-Days-of-Gatsby"]
+---
+
+_Gatsby was named the [#1 new technology to learn in 2020](https://www.cnbc.com/2019/12/02/10-hottest-tech-skills-that-could-pay-off-most-in-2020-says-new-report.html)!_
+
+_To help you learn about Gatsby and our ecosystem, we invite you to take the #100DaysOfGatsby challenge! If you are new to Gatsby, you can follow along with our beginner-friendly weekly prompts. Or if you are familiar with Gatsby and want to go deeper, we invite you to [build your first Gatsby Theme](/docs/themes/building-themes/)._
+
+_Learn more about [#100DaysOfGatsby here](/blog/100days)!_
+
+## Challenge 12: Add Gated Content to Your Website
+
+Did you know Gatsby can be used for websites as well as dynamic apps? Dustin Schau presented about this topic at Gatsby Days London:
+
+https://www.youtube.com/watch?v=zeVC-gD3u7M
+
+For example, if your project needs private routes, or sections of the site that only authenticated users can view, Gatsby can enable that with just a plugin, or by creating a few components from scratch. In the following resources we invite you to try both paths, and experiment with powerful third-party authentication services.
+
+### Gatsby for Apps Resources
+
+#### Overview & Examples
+
+First, get familiar with how [Gatsby works for apps](/docs/adding-app-and-website-functionality/).
+
+Then [watch this helpful livestream](/blog/2019-03-21-add-auth0-to-gatsby-livestream/) that covers adding an authentication service called Auth0 to your site.
+
+Lastly, play with live examples of these features by signing in to the [Gatsby Swag Store](https://store.gatsbyjs.org/), and [Gatsby Cloud](https://gatsbyjs.com/cloud)
+
+#### The Plugin Path
+
+To get started quickly, use `gatsby-plugin-create-client-paths` to create private client routes in your Gatsby site. [Learn more](/packages/gatsby-plugin-create-client-paths).
+
+#### The Hand-Rolled Path
+
+[Read this tutorial and handy illustration](/docs/client-only-routes-and-user-authentication/) that walks you through adding private routes and authentication in Gatsby.
+
+### What to Do If You Need Help
+
+If you get stuck during the challenge, you can ask for help from the [Gatsby community](/contributing/community/) and the [ASKGatsbyJS](https://twitter.com/AskGatsbyJS) Twitter account. You can find fellow Gatsby Developers on [Discord](https://discordapp.com/invite/gatsby), [Reddit](https://www.reddit.com/r/gatsbyjs/), [Spectrum](https://spectrum.chat/gatsby-js), and [Dev](https://dev.to/t/gatsby).

docs/blog/2018-2-27-why-i-upgraded-my-website-to-gatsbyjs-from-jekyll/index.md

@@ -100,7 +100,7 @@ Because of the APIs exposed by Gatsby for interfacing with its internals, powerf
 
 The [Node.js APIs](/docs/node-apis/) let plugins extend or modify the heavy lifting performed by the Node.js process when compiling the application. Your gatsby-node.js file can export functions which modify the GraphQL data that is provided to React components when they are rendered. The APIs are also used by plugins to extend the internals of Gatsby e.g. the default webpack config can also be customized here.
 
-Take the example of what happens during the processing of markdown files into pages. The [gatsby-source-filesystem](/packages/gatsby-source-filesystem) plugin scans directories and from files it finds, creates File nodes. These File nodes are then processed by [gatsby-transformer-remark](https://github.com/gatsbyjs/gatsby/tree/a3fea82b4d4b4c644156e841401821933e8d694a/packages/gatsby-transformer-remark) , parsing the markup into HTML with the [Remark](https://remark.js.org/) markdown processor.
+Take the example of what happens during the processing of markdown files into pages. The [gatsby-source-filesystem](/packages/gatsby-source-filesystem) plugin scans directories and from files it finds, creates File nodes. These File nodes are then processed by [gatsby-transformer-remark](https://github.com/gatsbyjs/gatsby/tree/a3fea82b4d4b4c644156e841401821933e8d694a/packages/gatsby-transformer-remark), parsing the markup into HTML with the [Remark](https://remark.js.org/) markdown processor.
 
 #### Server-side Rendering APIs
 

docs/blog/2019-03-15-design-code-blog-post/index.md

@@ -16,7 +16,7 @@ Design+Code started in 2015 when Meng To began with a digital book on designing
 
 ![](./images/cyfa.png)
 
-[Thomas Wang](https://twitter.com/thomaswangio "Twitter"), UI Developer at Design+Code, shared some of the important details of the rebuild, as well as the benefits their Gatsby-fueled site has provided their new offerings.
+[Thomas Wang](https://twitter.com/ThomasWang "Twitter"), UI Developer at Design+Code, shared some of the important details of the rebuild, as well as the benefits their Gatsby-fueled site has provided their new offerings.
 
 <Pullquote citation="Thomas Wang">
   We needed a new CMS to handle the amount of content we were creating and a

docs/blog/2019-04-30-how-to-build-a-blog-with-wordpress-and-gatsby-part-2/index.md

@@ -270,7 +270,6 @@ The code below pulls in the data for blog posts from WordPress and creates a pag
 
 // You can delete this file if you're not using it
 const path = require(`path`)
-const { createFilePath } = require(`gatsby-source-filesystem`)
 
 exports.createPages = async ({ graphql, actions, reporter }) => {
   const { createPage } = actions

docs/blog/2019-08-02-what-is-jsx-pragma/index.md

@@ -8,7 +8,7 @@ tags:
   - theme-ui
 ---
 
-If you’re looking into using [Theme UI](https://theme-ui.com/) , you’ll come across some (potentially) unfamiliar looking syntax:
+If you’re looking into using [Theme UI](https://theme-ui.com/), you’ll come across some (potentially) unfamiliar looking syntax:
 
 ```jsx
 /** @jsx jsx */

docs/blog/2019-12-12-how-we-accidentally-launched-a-popular-gatsby-plugin/index.md

@@ -60,7 +60,7 @@ I noticed there were some more downsides to Amplify:
 
 - Gatsby allows you to have [routes that only exist on the client side](/docs/building-apps-with-gatsby/#client-only-routes--user-authentication).
 
-- Essentially, you declare a starting point — say for example: /users/, and anything past that starting point will get picked up by the client side. Once the client navigates to /users/1, it will dynamically fetch that user from some sort of API. This is great and allows for very hybrid, partially static, partially dynamic applications. However, when people directly navigate to /users/1 , they will get a 404 because it simply does not exist on the serverside, which is kind of an issue.
+- Essentially, you declare a starting point — say for example: /users/, and anything past that starting point will get picked up by the client side. Once the client navigates to /users/1, it will dynamically fetch that user from some sort of API. This is great and allows for very hybrid, partially static, partially dynamic applications. However, when people directly navigate to /users/1, they will get a 404 because it simply does not exist on the serverside, which is kind of an issue.
 
 - We already had a CI service ourselves, and weren’t really interested in learning all these Amplify-specific things that we already had working ourselves just fine.
 

docs/docs/awesome-gatsby-resources.md

@@ -93,6 +93,7 @@ See the [unofficial list of themes](https://gatsbytemplates.io/)
 - [Deploying Your First Gatsby Site to Netlify](https://scotch.io/tutorials/deploying-your-first-gatsby-site-to-netlify)
 - [Add a chat widget to your Gatsby blog](https://pusher.com/tutorials/chat-gatsby/)
 - [Headless WordPress: Why Gatsby Should Be Next on Your List of Things to Learn](https://deliciousbrains.com/gatsby-headless-wordpress/)
+- [Gatsby Tutorials \[video series\] — Michael Uloth](https://www.youtube.com/watch?v=jAa1wh5ATm0&list=PLHBEcHVSROXQQhXpNhmiVKKcw72Cc0V-U)
 
 ### German
 

docs/docs/deploying-to-cloudflare-workers.md

@@ -121,4 +121,4 @@ Set up `CF_API_TOKEN` in GitHub secrets with appropriate values from [Quick Star
 ## Additional resources
 
 - [Quickstart for Workers Sites](https://developers.cloudflare.com/workers/sites/start-from-existing/)
-- [Github Action wrangler plugin](https://github.com/cloudflare/wrangler-action)
+- [GitHub Action wrangler plugin](https://github.com/cloudflare/wrangler-action)

docs/docs/gatsby-link.md

@@ -389,6 +389,16 @@ onClick = () => {
 }
 ```
 
+## Handling stale client-side pages
+
+Gatsby's `<Link>` component will only fetch each page's resources once. Updates to pages on the site are not reflected in the browser as they are effectively "locked in time". This can have the undesirable impact of different users having different views of the content.
+
+In order to prevent this staleness, Gatsby requests an additional resource on each new page load: `app-data.json`. This contains a hash generated when the site is built; if anything in the `src` directory changes, the hash will change. During page loads, if Gatsby sees a different hash in the `app-data.json` than the hash it initially retrieved when the site first loaded, the browser will navigate using `window.location`. The browser fetches the new page and starts over again, so any cached resources are lost.
+
+However, if the page has previously loaded, it will not re-request `app-data.json`. In that case, the hash comparison will not occur and the previously loaded content will be used.
+
+> **Note:** Any state will be lost during the `window.location` transition. This can have an impact if there is a reliance on state management, e.g. tracking state in [wrapPageElement](/docs/browser-apis/#wrapPageElement) or via a library like Redux.
+
 ## Additional resources
 
 - [Authentication tutorial for client-only routes](/tutorial/authentication-tutorial/)

docs/docs/glossary.md

@@ -34,7 +34,7 @@ A tool that lets you write the most modern [JavaScript](#javascript), and on [bu
 
 The behind the scenes that the [public](#public) does not see. This often refers to the control panel of your [CMS](#cms). These are often powered by server-side programming languages such as Node.js, PHP, Go, ASP.net, Ruby, or Java.
 
-### Build
+### [Build](/docs/glossary/build/)
 
 In Gatsby, this is the process of taking your code and content and packaging it into a website that can be hosted and accessed. Commonly referred to as _build time_. See also: [backend](#backend) and [server-side](#server-side).
 

docs/docs/glossary/build.md

@@ -0,0 +1,33 @@
+---
+title: Build
+disableTableOfContents: true
+---
+
+Learn what _build_ means and how to set up a build process for your Gatsby project.
+
+## What is a build?
+
+_Build_ refers to the process of compiling your site. During a build, or at _build time_, your project gets transformed from component files to optimized HTML, CSS, and JavaScript files that you can [deploy](/docs/glossary#deploy) to your hosting provider.
+
+There are a few ways to create a build. You can build your site locally on your computer using the [Gatsby CLI](/docs/gatsby-cli/#build), and then deploy changes to your [host](/docs/glossary#hosting). If you use [Gatsby Cloud](https://www.gatsbyjs.com/), you can take advantage of [Gatsby Builds](/blog/2020-01-27-announcing-gatsby-builds-and-reports/), a feature available with every Gatsby Cloud account. You can also use a [continuous deployment](/docs/glossary/continuous-deployment/) service such as [AWS Amplify](/docs/deploying-to-aws-amplify/) or [Netlify](/docs/deploying-to-netlify/).
+
+For larger teams or larger projects, you may want to use a continuous deployment approach to create builds. Each CD/CI service works slightly differently. Almost all of them, however, use the contents of a Git repository to build your site.
+
+Gatsby Cloud, for example, integrates with [GitHub](https://github.com/), and a number of hosted [content management systems](/docs/glossary#cms). Gatsby Cloud creates a new build after every commit or content change, although you can also trigger a build manually.
+
+### Using Gatsby <abbr>CLI</abbr>
+
+For smaller teams and projects, use `gatsby build`. The `gatsby build` command is part of the Gatsby command line interface (or CLI). You'll need to install the CLI interface to create a site with Gatsby. Install it globally using [npm](/docs/glossary/#npm).
+
+```shell
+npm install -g gatsby-cli
+```
+
+Installing `gatsby-cli` globally makes Gatsby commands available system-wide. You'll use `gatsby new` to [create a new site](/tutorial/part-zero/#create-a-gatsby-site), and `gatsby develop` to start a development server on your local machine.
+
+When you're ready to publish your project, run the `gatsby build` command to create a production-ready version of your site. Once built, you can use an SFTP client, the [rsync](https://en.wikipedia.org/wiki/Rsync) utility, or similar tool to transfer these files to your host.
+
+### Learn more about builds
+
+- [Deploying and Hosting](/docs/deploying-and-hosting/) from the Gatsby docs
+- How to enable super fast [Distributed Builds](https://www.gatsbyjs.com/docs/distributed-builds/) for Gatsby Cloud

docs/docs/glossary/continuous-deployment.md

@@ -5,7 +5,7 @@ disableTableOfContents: true
 
 ## What is continuous deployment?
 
-Continuous deployment (CD) is the automation of code deployments. In a continuous deployment system, you don't push a <q>Deploy</q> button or run a `deploy` command. Instead, you build a _pipeline_ &mdash; a process that builds and releases code automatically, without human intervention.
+Continuous deployment (CD) is the automation of code deployments. In a continuous deployment system, you don't push a <q>Deploy</q> button or run a `deploy` command. Instead, you build a _pipeline_ &mdash; a process that [builds](/docs/glossary/build/) and releases code automatically, without human intervention.
 
 You'll most likely use a service to create your continuous deployment pipeline. Services such as [Netlify](http://netlify.com/), [AWS Amplify](https://aws.amazon.com/amplify/), [Azure](https://azure.microsoft.com/en-us/), and [Zeit](https://zeit.co/) are popular with Gatsby users. Or you can use [Gatsby Builds](/blog/2020-01-27-announcing-gatsby-builds-and-reports/), a feature of the [Gatsby Cloud](https://www.gatsbyjs.com/) service.
 

docs/docs/recipes/working-with-themes.md

@@ -55,7 +55,7 @@ module.exports = {
 }
 ```
 
-4. Run `gatsby develop` , the theme should be available at `http://localhost:8000/{basePath}`
+4. Run `gatsby develop`, the theme should be available at `http://localhost:8000/{basePath}`
 
 > To learn how to further customize a theme, check out the available paths on [Gatsby-theme-blog Documentation](https://www.npmjs.com/package/gatsby-theme-blog).
 

docs/docs/sourcing-from-buttercms.md

@@ -45,7 +45,7 @@ Run this in your terminal:
 ### Adding configuration
 
 Here you'll specify the config that will be needed to pull down data from ButterCMS.
-Make sure to add your **API_TOKEN** from your dashboard. In this guide you will be creating `faq_items`, `faq_headline`, `homepage` , `customer_case_study` as stated in the config below. Do well to change it if you named it something differently.
+Make sure to add your **API_TOKEN** from your dashboard. In this guide you will be creating `faq_items`, `faq_headline`, `homepage`, `customer_case_study` as stated in the config below. Do well to change it if you named it something differently.
 
 ```javascript:title=gatsby-config.js
 module.exports = {

docs/docs/typography-js.md

@@ -10,7 +10,11 @@ Typography.js is a JavaScript library that allows you to explore the typographic
 
 Gatsby has the plugin `gatsby-plugin-typography` to integrate Typography.js into your project.
 
-You can install the plugin and its peer dependencies into your project by running the command `npm install gatsby-plugin-typography react-typography typography --save`
+You can install the plugin and its peer dependencies into your project by running the following command:
+
+```shell
+npm install gatsby-plugin-typography react-typography typography
+```
 
 After the installation of the plugin is complete, navigate to your `gatsby-config.js` file located in the root of your project's directory and add the plugin to the configuration: