Merge branch 'master' of https://github.com/gatsbyjs/gatsby into fix/g…

…atsbyjsGH-18284-schema-doc

docs/categories.yml

@@ -15,6 +15,7 @@ starter:
   - CMS:WordPress
   - CMS:sanity.io
   - CMS:Strapi
+  - CMS:Kontent
   - CMS:Forestry.io
   - CMS:Other
   - Disqus

docs/contributing/code-of-conduct.md

@@ -4,17 +4,11 @@ title: Gatsby Contributor Covenant Code of Conduct
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of
-experience, nationality, personal appearance, race, religion, or sexual identity
-and orientation.
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment
-include:
+Examples of behavior that contributes to creating a positive environment include:
 
 - Using welcoming and inclusive language
 - Being respectful of differing viewpoints and experiences
@@ -24,49 +18,29 @@ include:
 
 Examples of unacceptable behavior by participants include:
 
-- The use of sexualized language or imagery and unwelcome sexual attention or
-  advances
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
 - Trolling, insulting/derogatory comments, and personal or political attacks
 - Public or private harassment
-- Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-- Other conduct which could reasonably be considered inappropriate in a
-  professional setting
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
 
 ## Our Responsibilities
 
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
 
-Project maintainers have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned with this code of conduct, or to ban temporarily or permanently any
-contributor for other behaviors that they deem inappropriate, threatening,
-offensive, or harmful.
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this code of conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
 
 ## Scope
 
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at
-[conduct@gatsbyjs.com](mailto:conduct@gatsbyjs.com). All complaints will be
-reviewed and investigated and will result in a response that is deemed necessary
-and appropriate to the circumstances. The project team is obligated to maintain
-confidentiality with regard to the reporter of an incident. Further details of
-specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [conduct@gatsbyjs.com](mailto:conduct@gatsbyjs.com). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+When faced with repeated bad faith comments or harassment after an earnest attempt to mediate an issue, the Gatsby team reserves the right to remove someone from the GitHub repository and/or block them on social media. This decision will always be made with consensus from more than one team member.
 
 ## Attribution
 

docs/contributing/gatsby-docs-translation-guide.md

@@ -29,6 +29,7 @@ Changes to the meaning of a text or code example should be done in the main [Eng
 The first step for starting a new translation is to check what exists. So far, there are repositories for the following languages:
 
 - [Brazilian Portuguese](https://github.com/gatsbyjs/gatsby-pt-BR)
+- [Dutch](https://github.com/gatsbyjs/gatsby-nl)
 - [German](https://github.com/gatsbyjs/gatsby-de)
 - [Indonesian](https://github.com/gatsbyjs/gatsby-id)
 - [Italian](https://github.com/gatsbyjs/gatsby-it)

docs/contributing/gatsby-style-guide.md

@@ -149,7 +149,7 @@ abstract syntax tree (AST) is ..."
 
 ### Use SEO optimized titles
 
-This explains how to create a doc that shows up in search engines like Google or Bing.
+This explains how to account for Search Engine Optimization (SEO) and create a doc that shows up in search engines like Google or Bing.
 
 When you create the new guide or tutorial under `/docs/`, you’ll either create a file or a folder if there will be images pulled into the doc.
 

docs/contributing/managing-pull-requests.md

@@ -20,7 +20,7 @@ Some general things to verify in a pull request are:
 
 - Links ought to be relative instead of absolute when linking to docs (`/docs/some-reference/` instead of `https://www.gatsbyjs.org/docs/some-reference/`)
 - Language ought to be inclusive and accessible
-- Issues and RFCs (if any) that this PR addresses ought to be linked to
+- Issues and Requests for Comments (RFCs) (if any) that this PR addresses ought to be linked to
 
 > 💡 When looking at a PR for the first time, it can help to read up on linked issues or [RFCs](/contributing/rfc-process/) (if there are any) to gain context on what the PR intends to add or fix.
 

docs/docs/adding-react-components.md

@@ -0,0 +1,84 @@
+---
+title: Adding React Components
+---
+
+This guide covers how to add React components to your Gatsby site.
+
+## React components
+
+React components are prebuilt elements or groups of elements that can be used to split your User Interface (UI) into independent, reusable pieces. There are multiple types of components you can write: this guide covers functional components. For more in-depth information on writing React components including classes, check out the [React documentation](https://reactjs.org/docs/components-and-props.html).
+
+Components also offer the ability to be customized using inputs, better known as "props" (properties). Props can be of any JavaScript type, such as Boolean, String, Object, Array or almost anything you can think of.
+
+For example, you could use a component for Buttons on your site. This would enable them to be used multiple times across pages with different labels or actions each time.
+
+## Importing React components
+
+In Gatsby, when using React components, you can import and use them like you would in a React application. Here's an example of the [Gatsby Link](/docs/gatsby-link/) component in action, which brings with it extra functionality for performance:
+
+```jsx
+import React from "react"
+import { Link } from "gatsby"
+
+export default () => (
+  <div>
+    <Link to="/contact/">Contact</Link>
+  </div>
+)
+```
+
+### Importing third-party components
+
+Just like React, Gatsby also supports third-party components and libraries. You can install a third-party component or library via your package manager. We tend to favour and use npm and we will reflect this in our examples.
+
+Here's an example of adding a third-party component to your site.
+
+First, you have to install the component or library's package via a package manager. It's recommended not to mix package managers, so if you use npm, don't use another and vice versa.
+
+```shell
+npm install @material-ui/core
+```
+
+After you've installed a package, import and use it in your page's source:
+
+```jsx:title=my-page.jsx
+import React from "react"
+
+// import my fancy third-party component
+import Button from "@material-ui/core/Button"
+
+export default () => (
+  <div>
+    <p>This is my super awesome page made with Gatsby!</p>
+
+    {/* use my fancy third-party component */}
+    <Button>Fancy button!</Button>
+  </div>
+)
+```
+
+## Things to watch out for
+
+Since Gatsby uses Server-Side Rendering (SSR) to generate your site's pages, the JSX code you write is usually compiled before the browser loads the page. Because of this, certain features are not available at compile time and can cause a build error.
+
+### Use of browser globals
+
+Some components or code reference browser globals such as `window`, `document` or `localStorage`. These objects are not available at [build](/docs/glossary#build) time and can result in a webpack error when compiling:
+
+```
+WebpackError: ReferenceError: window is not defined
+```
+
+To learn more about solutions for supporting SSR and client-side libraries, check out the related section on the [Porting from Create React App documentation](/docs/porting-from-create-react-app-to-gatsby#server-side-rendering-and-browser-apis).
+
+#### Fixing third-party modules
+
+Some packages expect `window` or another browser global to be defined. These packages will have to be patched.
+
+You can learn how to patch these packages on the [Debugging HTML Builds documentation](docs/debugging-html-builds/#fixing-third-party-modules).
+
+### Components without server-side rendering
+
+Server-side rendering means pages and content are built out by the Node.js server and then sent to a browser ready to go. It’s like your pages are constructed before even being sent to the user. Gatsby is server-side rendered at build time, meaning that the code that gets to your browser has already been run to build pages and content, but this doesn’t mean you can’t still have dynamic pages.
+
+Some React components don't have server-side rendering support (SSR) out-of-the-box so you might have to add SSR yourself.

docs/docs/debugging-the-build-process.md

@@ -29,7 +29,7 @@ exports.onCreateNode = args => {
 
 There is a bug in this code and using it will produce the error below:
 
-```
+```js
 TypeError: Cannot read property 'internal' of undefined
 
   - gatsby-node.js:6 Object.exports.onCreateNode.args [as onCreateNode]
@@ -42,11 +42,11 @@ One of the fastest ways to gain insight into Gatsby's build process is using the
 
 Adding a `console.log` statement in the sample from above will print the variable into your terminal. There you might notice that `args` contains a lower-cased node variable.
 
-```diff:title=gatsby-node.js
+```js:title=gatsby-node.js
 const { createFilePath } = require("gatsby-source-filesystem")
 
 exports.onCreateNode = args => {
-+ console.log(args)
+  console.log(args) // highlight-line
   const { actions, Node } = args
   if (Node.internal.type === "MarkdownRemark") {
     const { createNodeField } = actions

docs/docs/eslint.md

@@ -37,3 +37,5 @@ module.exports = {
   extends: `react-app`,
 }
 ```
+
+If you want to disable ESLint completely, create an empty `.eslintrc` file.

docs/docs/gatsby-core-philosophy.md

@@ -163,6 +163,6 @@ Some things we do in order to create an inclusive, welcoming community include:
 - Active gratitude
 - [Active mentorship](/contributing/pair-programming/)
 
-We’ve built an active community with hundreds of contributors, and we want to live the example of what a great open source community can be.
+We’ve built an active community with thousands of contributors, and we want to live the example of what a great open source community can be.
 
 [See more here](https://www.youtube.com/watch?v=8ARA7AD4yPs&feature=youtu.be&list=PLz8Iz-Fnk_eQGt4-VFFCXYuYcuKaw4F07)

docs/docs/porting-from-create-react-app-to-gatsby.md

@@ -122,6 +122,7 @@ Some common globals that would need to be protected are:
 - `window`
 - `localStorage`
 - `navigator`
+- `document`
 
 Additionally, some packages that depend on globals existing (e.g. `react-router-dom`) may need to be [patched](/docs/debugging-html-builds/#fixing-third-party-modules) or migrated to other packages.
 
@@ -131,11 +132,53 @@ These are only a few examples, though all can be fixed in one of two ways:
 
 ```jsx
 if (typeof window !== `undefined`) {
-  // code using window like window.location...
+  // code that references a browser global
+  window.alert("Woohoo!")
 }
 ```
 
-2. moving references to globals into a `componentDidMount` or `useEffect` hook:
+2. For class components: moving references to browser globals into a `componentDidMount`
+
+```jsx
+
+import React, { Component } from "react"
+
+class MyComponment() extends Component {
+  render() {
+    window.alert("This will break the build")
+
+    return (
+      <div>
+        <p>Component</p>
+      </div>
+    )
+  }
+}
+```
+
+Would be changed into:
+
+```jsx
+
+import React, { Component } from "react"
+
+class MyComponment() extends Component {
+  componentDidMount() {
+    // code that references the browser global
+    window.alert("This won't break the build")
+  }
+
+  render() {
+    return (
+      <div>
+        <p>Component</p>
+      </div>
+    )
+  }
+}
+```
+
+3. For function components: moving references to browser globals into a `useEffect` hook
 
 ```jsx
 import React from "react"
@@ -163,6 +206,12 @@ const Foo = () => {
 export default Foo
 ```
 
+If these browser globals aren't protected correctly, you'll see a webpack error like the one below when building your site:
+
+```
+WebpackError: ReferenceError: window is not defined
+```
+
 For more information about errors encountered during builds, see the doc on [debugging HTML builds](/docs/debugging-html-builds/). For more information about React hooks, check out the [React docs](https://reactjs.org/docs/hooks-effect.html).
 
 ### Routing