gatsbyjs · lex111 · Feb 22, 2020 · Jan 22, 2020 · Jan 22, 2020 · Jan 22, 2020
diff --git a/docs/contributing/docs-and-website-components.md b/docs/contributing/docs-and-website-components.md
@@ -3,12 +3,6 @@ title: Docs and Website Components
 tableOfContentsDepth: 2
 ---
 
-import LayerModel from "../../www/src/components/layer-model"
-import HorizontalNavList from "../../www/src/components/horizontal-nav-list"
-import Breadcrumb from "../../www/src/components/docs-breadcrumb"
-import { itemListContributing } from "../../www/src/utils/sidebar/item-list"
-import TableOfContents from "../../www/src/components/docs-table-of-contents"
-
 The Gatsbyjs.org site has a handful of components that have been developed to facilitate writing new content for the blog and the docs. There are also components that help organize and lay out content in various pages across the website.
 
 This guide documents what components are available and explains how to use them. You can also refer to the [code for this page on GitHub](https://github.com/gatsbyjs/gatsby/blob/master/docs/contributing/docs-and-website-components.md) to see to how each component can be used, because they are all embedded here!
@@ -130,14 +124,6 @@ Rendered, the component looks like this:
   To improve is to change, so to be perfect is to have changed often.
 </Pullquote>
 
----
-
-## Other available components
-
-Other less commonly used components aren't globally available, but can imported at the top of a Markdown file and used in other docs.
-
----
-
 ### Layer Model
 
 The `<LayerModel />` was made to help explain concepts of how Gatsby works at a high level. It conceptually breaks Gatsby into different layers and shows how data is pulled, aggregated, and eventually rendered as an app. It's used on docs pages to help explain how Gatsby works at different levels.
@@ -168,7 +154,7 @@ When used, it looks like this:
 
 ### Horizontal Navigation List
 
-The `<HorizontalNavList />` was made for the [Glossary](/docs/glossary/), and renders a list of links to alphabetical subheadings on the page in a horizontal format. Because of its specific use case, it isn't made globally available but can be imported if needed on other pages.
+The `<HorizontalNavList />` was made for the [Glossary](/docs/glossary/), and renders a list of links to alphabetical subheadings on the page in a horizontal format.
 
 #### Usage
 
@@ -212,169 +198,6 @@ items={[
 slug={props.slug}
 />
 
-### Breadcrumb
-
-The `<Breadcrumb />` component is used in layout files to display the hierarchy of pages a user is currently browsing on.
-
-#### Usage
-
-The Breadcrumb component takes one prop:
-
-- `location` - an object provided in the props of page templates by default
-- `itemList` - an object comprised of the docs hierarchical structure
-
-<!-- prettier-ignore -->
-```jsx
-import Breadcrumb from "../../www/src/components/docs-breadcrumb"
-
-<Breadcrumb location={props.location} itemList={itemList} />
-```
-
-_You can also refer to [an example of usage of the Breadcrumb in the Gatsbyjs.org source code](https://github.com/gatsbyjs/gatsby/blob/1d65ce051967dda5c4a89da920fc34692524e237/www/src/templates/template-docs-markdown.js#L82)_
-
-#### Optional `breadcrumbTitle` entries in sidebar files
-
-To alter the title of a doc that is displayed in the Breadcrumb component, a `breadcrumbTitle` is supported as a key in the [sidebar YAML files](https://github.com/gatsbyjs/gatsby/tree/master/www/src/data/sidebars). It is commonly used to provide an abbreviated version of a doc's title when displayed next to its parent page title, e.g. shortening "Adding a Custom webpack Config" to "webpack Config".
-
-#### Sample
-
-Rendered, it looks like this:
-
-<Breadcrumb
-location={{
-    pathname: "/contributing/docs-and-website-components/",
-  }}
-itemList={itemListContributing}
-/>
-
----
-
-### Table of Contents
-
-The `<TableOfContents />` component is used to render a list of subheaders from a docs page and automatically provide deep links to them.
-
-#### Usage
-
-The component takes 2 props:
-
-- `location` - an object provided in the props of page templates by default
-- `page` - an object with data passed in from the sites `gatsby-node.js` that contains information from the MDX plugin about the structure of headings
-
-<!-- prettier-ignore -->
-```jsx
-import TableOfContents from "../../www/src/components/docs-table-of-contents"
-
-<TableOfContents location={props.location} page={page} />
-```
-
-_You can also refer to [an example of usage of the Table of Contents in the Gatsbyjs.org source code](https://github.com/gatsbyjs/gatsby/blob/1d65ce051967dda5c4a89da920fc34692524e237/www/src/templates/template-docs-markdown.js#L121)_
-
-The Table of Contents component also has some optional configurations that can be set in the frontmatter of a doc's markdown.
-
-In docs where the Table of Contents isn't required and should be disabled, a key in the frontmatter called `disableTableOfContents` can be set to `true` like this:
-
-```markdown
----
-title: Glossary
-disableTableOfContents: true
----
-
-When you're new to Gatsby there can be a lot of words to learn...
-```
-
-In other docs where the Table of Contents is extremely long it can make sense to only show headers from the doc up to a certain level, rather than all subheadings. You can set the `tableOfContentsDepth` key to a number that will limit the subheadings shown in the table of contents to that "depth". If it is set to 2, `<h2>`/`##`, and `<h3>`/`###` headers will be listed, if set to 3, `<h2>`/`##`, `<h3>`/`###`, and `<h4>`/`####` will all be shown. It is set like this:
-
-```markdown
----
-title: Glossary
-tableOfContentsDepth: 2
----
-
-When you're new to Gatsby there can be a lot of words to learn...
-```
-
-#### Sample
-
-The Table of Contents looks like this when rendered (and is also displayed on the right hand side of the page):
-
-<TableOfContents
-location={{ pathname: "/contributing/docs-and-website-components/" }}
-page={{
-    frontmatter: {
-      title: "Docs and Website Components",
-      tableOfContentsDepth: 2,
-    },
-    tableOfContents: {
-      items: [
-        {
-          url: "#globally-available-components",
-          title: "Globally available components",
-          items: [
-            {
-              url: "#guide-list",
-              title: "Guide list",
-            },
-            {
-              url: "#egghead-embed",
-              title: "Egghead embed",
-            },
-            {
-              url: "#pull-quote",
-              title: "Pull quote",
-            },
-          ],
-        },
-        {
-          url: "#other-available-components",
-          title: "Other available components",
-          items: [
-            {
-              url: "#layer-model",
-              title: "Layer model",
-            },
-            {
-              url: "#horizontal-navigation-list",
-              title: "Horizontal navigation list",
-            },
-            {
-              url: "#breadcrumb",
-              title: "Breadcrumb",
-            },
-            {
-              url: "#table-of-contents",
-              title: "Table of Contents",
-            },
-          ],
-        },
-        {
-          url: "#writing-content-in-markdown",
-          title: "Writing content in markdown",
-          items: [
-            {
-              url: "#code-blocks",
-              title: "Code blocks",
-            },
-          ],
-        },
-        {
-          url: "#styling-components-on-gatsbyjsorg-with-theme-ui",
-          title: "Styling components on Gatsbyjs.org with Theme-UI",
-          items: [
-            {
-              url: "#design-tokens",
-              title: "Design tokens",
-            },
-            {
-              url: "#the-sx-prop",
-              title: "The sx prop",
-            },
-          ],
-        },
-      ],
-    },
-  }}
-/>
-
 ---
 
 ## Writing content in Markdown

diff --git a/docs/contributing/docs-contributions.md b/docs/contributing/docs-contributions.md
@@ -98,20 +98,94 @@ It can be necessary to change a heading within the docs. It's important to note
 - Determine the URL you're looking for. `Changing headers` is linked with a URL ending in `changing-headers`, `Docs renaming instructions` becomes `docs-renaming-instructions`, etc.
 - Update all instances of the old URL to your new one. [Find and replace](https://code.visualstudio.com/docs/editor/codebasics#_search-across-files) in VS Code can help. Check that the context of the original link reference still makes sense with the new one.
 
+## Adding a description
+
+The site automatically creates description tags in order to boost SEO:
+
+```html
+<meta name="description" content="Documentation of Gatsby" />
+<meta property="og:description" content="Documentation of Gatsby" />
+<meta name="twitter:description" content="Documentation of Gatsby" />
+```
+
+By default, this description is generated from the `page.excerpt`. If you would like to add a custom description, you can use the `description` frontmatter tag:
+
+```markdown
+---
+title: Gatsby Community Events
+description: Learn about other events happening around the globe to connect with other members of the Gatsby community
+---
+```
+
+## Configuring site navigation
+
+The docs include custom built components to aid with navigation. In order to customize the navigation experience, these components allow some configurations without changing any of the React code.
+
+### Adjusting breadcrumb titles
+
+The `<Breadcrumb />` component is used in layout files to display the hierarchy of pages a user is currently browsing on at the top of each doc.
+
+To alter the title of a doc that is displayed in the Breadcrumb component, `breadcrumbTitle` is supported as a key in the [sidebar YAML files](https://github.com/gatsbyjs/gatsby/tree/master/www/src/data/sidebars). It is commonly used to provide an abbreviated version of a doc's title when displayed next to its parent page title, e.g. shortening "Adding a Custom webpack Config" to "webpack Config".
+
+```yaml
+- title: Adding Page Transitions
+  link: /docs/adding-page-transitions/
+  breadcrumbTitle: Page Transitions # highlight-line
+```
+
+### Disabling or shortening Table of Contents
+
+The `<TableOfContents />` component is used to render a list of subheaders from a docs page and automatically provide deep links to them. It can be tweaked by values set in the frontmatter of a doc's markdown.
+
+In docs where the Table of Contents isn't required and should be disabled, a key in the frontmatter called `disableTableOfContents` can be set to `true` like this:
+
+```markdown
+---
+title: Glossary
+disableTableOfContents: true
+---
+
+When you're new to Gatsby there can be a lot of words to learn...
+```
+
+In other docs where the Table of Contents is extremely long it can make sense to only show headers from the doc up to a certain level, rather than all subheadings. You can set the `tableOfContentsDepth` key to a number that will limit the subheadings shown in the table of contents to that "depth". If it is set to 2, `<h2>`/`##`, and `<h3>`/`###` headers will be listed, if set to 3, `<h2>`/`##`, `<h3>`/`###`, and `<h4>`/`####` will all be shown. It is set like this:
+
+```markdown
+---
+title: Glossary
+tableOfContentsDepth: 2
+---
+
+When you're new to Gatsby there can be a lot of words to learn...
+```
+
+## Adding embedded GraphQL examples
+
+There are embedded examples in a few places in the docs (like the [GraphQL Reference guide](/docs/graphql-reference/)) that provide a working version of the code described. In the specific example of the GraphQL Query Options Reference page, these examples of the GraphiQL interface show how data can be queried from Gatsby's data layer.
+
+To write a new GraphQL example, a Codesandbox project with a Gatsby site can be opened at its server container link, for example: [https://711808k40x.sse.codesandbox.io/](https://711808k40x.sse.codesandbox.io/). Because Codesandbox is running a Gatsby site in [`develop` mode instead of `build` mode](/docs/overview-of-the-gatsby-build-process/) you can navigate to GraphiQL by adding `/___graphql` to the link. Write an example query, and when you have a query you are satisfied with, the query fields and names will be saved as URL parameters so you can share the link. Copy the URL and use it as the `src` of an iframe:
+
+```mdx
+Here's an example of a GraphQL query inline:
+
+<iframe src="https://711808k40x.sse.codesandbox.io/___graphql?query=query%20TitleQuery%20%7B%0A%20%20site%20%7B%0A%20%20%20%20siteMetadata%20%7B%0A%20%20%20%20%20%20title%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A&explorerIsOpen=false&operationName=TitleQuery" /> // highlight-line
+
+More markdown content...
+```
+
+> Note that you should set the `explorerIsOpen` parameter in the URL to `false` if it isn't already.
+
 ## Docs renaming instructions
 
 Sometimes it makes sense to move or rename a file as part of docs restructuring or for content clarification. While we recommend keeping URLs consistent as often as possible, here are some tips to minimize errors and keep the docs in a good state:
 
 - Run proposed structure changes by the Gatsby docs team in [a GitHub issue](/contributing/how-to-file-an-issue/) to ensure your change is accepted.
 - Update all instances of the old URL to your new one. [Find and replace](https://code.visualstudio.com/docs/editor/codebasics#_search-across-files) in VS Code can help. Check that the context of the original link reference still makes sense with the new one.
-- For SEO purposes, add a redirect to the `createPages` function in [`www/gatsby-node.js`](https://github.com/gatsbyjs/gatsby/tree/master/www/gatsby-node.js). Here's an example:
-
-```js:title=www/gatsby-node.js
-createRedirect({
-  fromPath: `/docs/source-plugin-tutorial/`,
-  toPath: `/docs/pixabay-source-plugin-tutorial/`,
-  isPermanent: true,
-})
+- For SEO purposes, add a redirect to [`www/redirects.yaml`](https://github.com/gatsbyjs/gatsby/tree/master/www/redirects.yaml). Here's an example:
+
+```yaml:title=www/redirects.yaml
+- fromPath: /docs/source-plugin-tutorial/
+  toPath: /docs/pixabay-source-plugin-tutorial/
 ```
 
 ## Claim your swag

diff --git a/docs/contributing/docs-templates.md b/docs/contributing/docs-templates.md
@@ -12,6 +12,8 @@ Here are some things to keep in mind when deciding where to contribute to Gatsby
 - [Recipes](#recipes) add concise, discoverable, and easy-to-follow instructions for common Gatsby tasks. They are smaller units than tutorials.
 - [Tutorials](#tutorials) should provide step-by-step guidance for Gatsby workflows, listing all pre-requisites and not assuming knowledge or skipping steps.
 
+When writing (or reviewing) learning materials that show Gatsby users how to complete tasks, you are expected to **test out any code examples or steps to ensure they work**. This can also help with writing in your own words, rather than copying from other sources. If you have a demo project or code example that strengthens docs and you don't know where to put it, mention it to the Gatsby Learning team in a PR.
+
 ### Why use templates?
 
 Here are templates (models) to follow when contributing to Gatsby docs to ensure that the docs accomplish their purpose. If you have a good reason to deviate from the following template structures, mention those reasons in the PR so others can give proper feedback.
@@ -198,6 +200,7 @@ A recipe should list requirements and include a few short instructions to comple
 
 The components of a recipe are:
 
+- Overview link on [`recipes.md`](https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/recipes.md)
 - The name of the recipe, which should describe a single task
 - A 1-2 sentence description motivating what the recipe is for
 - Prerequisites and requirements
@@ -209,8 +212,6 @@ Recipes should be short. This is accomplished by limiting steps to what is uniqu
 
 If you're finding a recipe is becoming too long to fit on the Docs Recipes page due to including many prerequisites or steps, consider writing a tutorial instead.
 
-> Note: If you add a new recipe to the existing sections, be sure to add it to the list on the [`recipes.md` landing page](https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/recipes.md)!
-
 ### Recipe categories
 
 Grouping recipes by topic will allow users to navigate and learn by subject matter. As recipes following the new format are introduced, you might find a section needs an h2 heading added for the group. The older-style recipes should be gradually replaced with actionable recipes following the template below.
@@ -235,6 +236,10 @@ Here's a template for a new recipe category:
 
 ### Recipe parts
 
+#### Overview link
+
+To make sure your recipe is linked from the overview page, you must add it to the appropriate category in [`recipes.md`](https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/recipes.md). Otherwise, it will be difficult for Gatsby users to find it, which isn't good for anyone!
+
 #### Title and description
 
 To help motivate the purpose of a recipe, its title should clearly indicate the task being covered; not just the tool or API being used. E.g. "Using the StaticQuery Component" is more descriptive than "StaticQuery".

diff --git a/docs/contributing/events.md b/docs/contributing/events.md
@@ -0,0 +1,11 @@
+---
+title: Gatsby Community Events
+description: Learn about other events happening around the globe to connect with other members of the Gatsby community
+---
+
+Interested in connecting with the Gatsby community in person? Take a look at the list below to see community-organized Gatsby events.
+
+Want to see your event featured here? [Submit your Gatsby event info!](https://airtable.com/shrpwc99yogJm9sfI)
+
+<Events />
+<EmailCaptureForm signupMessage="Want to keep up with the latest tips & tricks? Subscribe to our newsletter!" />