Merge branch 'master' into moonmeister/feat/sitemap-rewrite

* master: (183 commits)
  chore(gatsby-plugin-image): Remove version note (#30758)
  docs: retire 'How to Create Pages' stub and Recipes landing page (#30842)
  chore(docs): Fix typo (#30858)
  docs: fix invalid mailto links in 3.3 release notes (#30862)
  docs: release notes for 3.3 (#30837)
  fix(gatsby-source-wordpress): invalidate less queries during previews (#30770)
  fix(gatsby-starter-wordpress-blog): Fix altText (#30832)
  feat(contentful): warn users when using restricted content type names (#30715)
  Refactor: using-contentful to use gatsby-plugin-image exclusively (#30717)
  chore(gatsby-plugin-styled-components): Remove breaking changes section (#30806)
  fix(gatsby): webpack warnings are no longer in object format by default (#30801)
  fix(gatsby): Decode base path in runtime (#30682)
  fix(gatsby): "Cannot find module 'babel-preset-gatsby'" error (#30813)
  handle plugin parentDir resolution in resolvePlugin() (#30812)
  Port using-gatsby-image site to image plugin (#28489)
  fix(gatsby-source-contentful): De-dupe type names (#30834)
  feat(gatsby): Add aggregation resolvers (#30789)
  fix(gatsby-core-utils): fetch-remote-file download failure when missing content-length header (#30810)
  fix(renovate): add breaking minor updates to major updates list (#30676)
  chore(docs): Update migration guide for plugins that support both v2 & v3 (#30825)
  ...

.gitignore

@@ -51,6 +51,7 @@ __diff_output__/
 # misc
 .serverless/
 .eslintcache
+scripts/.env
 
 # lock files
 yarn.lock

README.md

@@ -7,12 +7,14 @@
   Gatsby v3
 </h1>
 
-<h3 align="center">
+<p align="center">
   ⚛️ 📄 🚀
-</h3>
-<h3 align="center">
-  Fast in every way that matters
-</h3>
+</p>
+<p align="center">
+  <strong>
+    Fast in every way that matters
+  </strong>
+</p>
 <p align="center">
   Gatsby is a free and open source framework based on React that helps developers build blazing fast websites and apps
 </p>
@@ -40,7 +42,7 @@
   </a>
 </p>
 
-<h3 align="center">
+<h2 align="center">
   <a href="https://www.gatsbyjs.com/docs/">Quickstart</a>
   <span> · </span>
   <a href="https://www.gatsbyjs.com/tutorial/">Tutorial</a>
@@ -56,7 +58,7 @@
   Support: <a href="https://twitter.com/AskGatsbyJS">Twitter</a>, <a href="https://github.com/gatsbyjs/gatsby/discussions">Discussions</a>
   <span> & </span>
   <a href="https://gatsby.dev/discord">Discord</a>
-</h3>
+</h2>
 
 Gatsby is a modern web framework for blazing fast websites.
 
@@ -138,6 +140,10 @@ We welcome suggestions for improving our docs. See the [“how to contribute”]
 
 **Start Learning Gatsby: [Follow the Tutorial](https://www.gatsbyjs.com/tutorial/) · [Read the Docs](https://www.gatsbyjs.com/docs/)**
 
+## 🚢 Release Notes
+
+Wondering what we've shipped recently? Check out our [release notes](https://www.gatsbyjs.com/docs/reference/release-notes) for key highlights, performance improvements, new features, and notable bugfixes.
+
 ## 💼 Migration Guides
 
 Already have a Gatsby site? These handy guides will help you add the improvements of Gatsby v3 to your site without starting from scratch!
@@ -161,7 +167,7 @@ This repository is a [monorepo](https://trunkbaseddevelopment.com/monorepos/) ma
 
 ### Contributing to Gatsby v2
 
-We are currently only accepting bug fixes for Gatsby v2. No new features will be accepted.
+We are only accepting critical security patches for Gatsby v2.
 
 ## 📝 License
 

benchmarks/create-pages/gatsby-node.js

@@ -1,10 +1,11 @@
 const NUM_PAGES = parseInt(process.env.NUM_PAGES || 5000, 10)
 
+const blankTemplate = require.resolve(`./src/templates/blank.js`)
 exports.createPages = ({ actions: { createPage } }) => {
   for (let step = 0; step < NUM_PAGES; step++) {
     createPage({
       path: `/path/${step}/`,
-      component: require.resolve(`./src/templates/blank.js`),
+      component: blankTemplate,
       context: {
         id: step,
       },

docs/contributing/blog-contributions.md

@@ -2,7 +2,9 @@
 title: Blog Contributions
 ---
 
-If you'd like to contribute a post to the Gatsby blog, please review the process and guidelines outlined below and submit your idea for the post to our [Gatsby blog proposal form](https://airtable.com/shr3449954866i3iF)
+Blog posts are a great way to share your own experiences working with Gatsby at work or on a personal project.
+
+If you'd like to contribute a post to the Gatsby blog, please review the process and guidelines outlined below and submit your post idea using the [Gatsby blog proposal form](https://airtable.com/shr3449954866i3iF).
 
 ## Blog proposal submission process
 

docs/contributing/docs-contributions/docs-structure.md

@@ -0,0 +1,43 @@
+---
+title: How the Docs are Structured
+---
+
+## Introduction
+
+If you're looking to contribute to the Gatsby documentation, it helps to first understand how the docs are organized. This page outlines the overall structure of the Gatsby documentation. It also provides guidance on when you might choose one type of documentation over another.
+
+## Documentation Types
+
+The [Gatsby documentation site](/docs) includes four different types of materials. Each one is tailored to meet a specific user need.
+
+- [**How-To Guides**](/docs/how-to/) are practical step-by-step guides to help readers achieve a specific goal. These are most useful when readers are trying to get something done.
+- [**Reference Guides**](/docs/reference/) are nitty-gritty technical descriptions of how Gatsby works. These are most useful when readers need detailed information about Gatsby's APIs.
+- [**Conceptual Guides**](/docs/conceptual/) are big-picture explanations of higher-level Gatsby concepts. These are most useful when readers want to deepen their understanding of a particular topic.
+- The [**Tutorial**](/docs/tutorial/) is a self-contained introduction that guides readers step-by-step through creating their first Gatsby site. This is most useful when readers are first getting started with Gatsby.
+
+![Each of the four types of docs has a different intended audience. The Tutorial is for learning-oriented readers, who want practical steps to help when they're studying. How-To Guides are for problem-oriented readers, who want practical steps to help when they're working. Reference Guides are for information-oriented readers, who want theoretical knowledge to help when they're working. Conceptual Guides are for understanding-oriented readers, who want theoretical knowledge to help when they're studying.](./doc-type-quadrants.svg)
+
+> This documentation structure is based on the [Diátaxis documentation system](https://diataxis.fr) created by Daniele Procida.
+
+### Choosing what type of doc to write
+
+Trying to decide which type of documentation is the best fit? Check out the following guides:
+
+- [How to Write a How-To Guide](/contributing/docs-contributions/how-to-write-a-how-to-guide/)
+- [How to Write a Reference Guide](/contributing/docs-contributions/how-to-write-a-reference-guide/)
+- [How to Write a Conceptual Guide](/contributing/docs-contributions/how-to-write-a-conceptual-guide/)
+- [How to Write a Tutorial](/contributing/docs-contributions/how-to-write-a-tutorial)
+
+The guides above provide more details about each type of documentation. They also include templates and tips for how to write them. Use these resources to make sure your docs contribution fits the overall documentation structure.
+
+Sometimes, a single concept will require some combination of these documentation types. For example, the `gatsby-plugin-image` documentation includes the following pieces:
+
+- [Gatsby Image plugin](/docs/reference/built-in-components/gatsby-plugin-image/): A Reference Guide to explain the plugin API and all its options.
+- [Using the Gatsby Image plugin](/docs/how-to/images-and-media/using-gatsby-plugin-image/): A How-To Guide to show practical examples of how to use the plugin.
+
+### Other types of documentation
+
+Aside from the four main documentation types, there are a few additional types of documentation found in the Gatsby repo. Check out the following guides for more information:
+
+- [How to Write a Plugin README](/contributing/docs-contributions/how-to-write-a-plugin-readme)
+- [How to Write a Starter README](/contributing/docs-contributions/how-to-write-a-starter-readme)

docs/contributing/docs-contributions/how-to-write-a-conceptual-guide.md

@@ -0,0 +1,30 @@
+---
+title: How to Write a Conceptual Guide
+---
+
+## What is a Conceptual Guide?
+
+A Conceptual Guide provides a big-picture explanation of higher-level Gatsby concepts. Conceptual Guides are most useful for readers who want to build a deeper understanding of a particular topic.
+
+Rather than focusing on specific technical details, Conceptual Guides take a step back to look at the broader picture. For example, it might explain [image optimizations](/docs/conceptual/using-gatsby-image/) or compare [build time and runtime data fetching](/docs/conceptual/data-fetching/).
+
+You can think of a Conceptual Guide as a discussion. It compares the benefits and risks of different approaches. It provides additional historical context to explain how things ended up the way they are.
+
+> For more information on Conceptual Guides, check out the [Diátaxis documentation system](https://diataxis.fr/explanation/), which the Gatsby docs are based on.
+>
+> **Note:** In the Diátaxis system, these types of docs are called "Explanations" instead of "Conceptual Guides".
+
+## A near-perfect example of a Conceptual Guide
+
+Want to see what a good Conceptual Guide looks like? Check out the [Conceptual Guide: Plugins, Themes, & Starters](/docs/conceptual/plugins-themes-and-starters/).
+
+## Conceptual Guide template
+
+Because of the open-ended nature of a Conceptual Guide, it's difficult to create a template for how to structure one.
+
+Instead, here's a list of questions to consider as you're writing:
+
+- What is the central, underlying concept for this topic? Why is that something worth learning about?
+- What historical background or past decisions would be helpful for newcomers trying to understanding this concept?
+- Are there any other solutions or approaches? What are the pros and cons of each approach?
+- What other viewpoints should be considered?

docs/contributing/docs-contributions/how-to-write-a-how-to-guide.md

@@ -0,0 +1,104 @@
+---
+title: How to Write a How-To Guide
+---
+
+## What is a How-To Guide?
+
+A How-To Guide is a practical step-by-step guide that helps readers achieve a specific goal. How-To Guides are most useful when readers want to get something done.
+
+How-To Guides work well for outlining procedures that readers need to follow. You can think of a How-To Guide as a recipe used in cooking. It walks you through the steps to complete a task, from start to finish. It should only include as much context as is needed to help users achieve their goal.
+
+A How-To Guide can include _some_ details to help users understand the steps they're following. For example, you should add a quick sentence before showing a code snippet, to explain what the code does (at a high level) and which pieces to pay special attention to. If you find yourself wanting to provide deeper explanations of how something works, consider creating a separate [Reference Guide](/contributing/docs-contributions/how-to-write-a-reference-guide) or [Conceptual Guide](/contributing/docs-contributions/how-to-write-a-conceptual-guide) and then linking to it in the How-To Guide.
+
+> For more information on How-To Guides, check out the [Diátaxis documentation system](https://diataxis.fr/how-to-guides/), which the Gatsby docs are based on.
+
+## How-To Guides audience
+
+How-To Guides are for anyone looking to complete a common Gatsby task, however they may appeal to intermediate to advanced learners due to their brevity and focus on Gatsby-specific details without going through every setup step.
+
+## How-To Guides tone and style
+
+How-To Guides are shorter and more concise than the Tutorial but more hands-on than Reference Guides. They should be friendly but information-dense. This is accomplished by focusing on only what is relevant and actionable to the given task, anticipating any new or difficult concepts with links to additional materials to continue learning.
+
+## A near-perfect example of a How-To Guide
+
+Want to see what a good How-To Guide looks like? Check out the [How-To Guide: Add a Plugin to Your Site](/docs/how-to/plugins-and-themes/using-a-plugin-in-your-site).
+
+## How-To Guide template
+
+The title of your How-To Guide should specify what it helps readers do. You should be able to add the words "how to" to the beginning and have it make sense. For example, if your guide is about "how to create a new layout component", the title would be "Create a New Layout Component."
+
+A How-To Guide should include the following sections:
+
+- **Introduction:** Provide some quick background information to help readers understand 1) what this How-To Guide will help them achieve and 2) why that's useful.
+- **Prerequisites:** Any additional information or setup readers will have to do before they can make use of this How-To Guide.
+- **Directions:** List out the steps that readers to follow to complete the task. Use code blocks to show exactly what readers should type in their own projects.
+- **Additional Resources:** Links to other docs or content that might be useful next steps for readers. Also, any resources that helped you write the How-To Guide.
+
+```markdown
+---
+title: Do Some Task
+---
+
+## Introduction
+
+The introductory paragraph should be a 2-3 sentence explanation of the
+main topic and answer the following questions:
+
+What is the purpose of this guide? What will readers have achieved by
+following the steps in this guide?
+
+Why is this process worth doing? How will it help readers improve their
+Gatsby site?
+
+## Prerequisites
+
+If applicable, list any prerequisites to reading and understanding your
+article.
+
+Does the reader need to read another document first, install a particular
+plugin, or already know a certain skill? List those things here.
+
+## Directions
+
+This section should be a step-by-step list of instructions for how readers
+can achieve the goal.
+
+1. Do the first thing.
+2. Do the next thing.
+
+Use code blocks to show exactly what readers should type. The
+Gatsby Style Guide includes tips for best practices when using code
+blocks:
+https://www.gatsbyjs.com/contributing/gatsby-style-guide/#format-code-blocks-inline-code-and-images
+
+If it's a particularly long list of directions, you can split the steps into
+sections. Use subheadings to label each chunk. For example:
+
+### Step 1: Do the first thing.
+
+1. The first step of the first thing.
+1. The second step of the first thing.
+
+### Step 2: Do some other thing.
+
+1. The first step of some other thing.
+1. The second step of some other thing.
+
+## Additional Resources
+
+Include other resources you think readers would benefit from or next steps
+they might want to take after reading your How-To Guide. You can also
+mention any resources that helped you write the article (blog posts, outside
+tutorials, etc.).
+
+Best-case scenario, these should be high-quality, evergreen
+(not quickly outdated) resources.
+
+- Link to a blog post
+- Link to a YouTube tutorial
+- Link to an example site
+- Link to source code for a live site
+- Links to relevant plugins
+- Links to starters
+```

docs/contributing/how-to-write-a-plugin-readme.md → docs/contributing/docs-contributions/how-to-write-a-plugin-readme.md

@@ -1,8 +1,9 @@
 ---
 title: How to Write a Plugin README
-issue: https://github.com/gatsbyjs/gatsby/issues/21599
 ---
 
+A plugin README is like a Reference Guide for a specific plugin. It should describe what the plugin does, how to install and configure it, and how to use it in your site.
+
 ## Near-perfect example of a plugin README
 
 [`gatsby-source-filesystem`](/plugins/gatsby-source-filesystem/)