benchmarks/gabe-fs-markdown-images/.gitignore

@@ -0,0 +1,74 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# dotenv environment variable files
+.env*
+
+# gatsby files
+.cache/
+public
+
+# Mac files
+.DS_Store
+
+# Yarn
+yarn-error.log
+.pnp/
+.pnp.js
+# Yarn Integrity file
+.yarn-integrity
+yarn.lock
+
+generated_articles
+generated_images
+generated_image_pools

benchmarks/gabe-fs-markdown-images/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Gatsbyjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

benchmarks/gabe-fs-markdown-images/README.md

@@ -0,0 +1,63 @@
+# Baseline Gatsby Benchmark: fs + markdown + images
+
+This is a baseline benchmark site in the Gabe project.
+
+This site in particular tracks Markdown performance for individual files per page that also have an image (not part of the markdown).
+
+The site can generate an arbitrary amount of super simple pages. Each page has a small header, a quote, and two small paragraphs of random text. No images, because we want to benchmark Markdown.
+
+The results of this benchmark can be compared to the results of the `gabe-fs-markdown` benchmark, to see a tentative impact of using images in markdown.
+
+## Install
+
+Run `yarn` or `npm install`
+
+## Usage
+
+Unlike most other gabe benchmarks, the generation part is a little more complex because it will generate image file pools first and then copy images from those pools into their destination.
+
+### Image generation
+
+Image generation is rather expensive. The default size for 128k can take 2 hours single threaded. For that reason, the image generation can use workers instead.
+
+Recommended way for larger pages is to first generate all the images up to the amount you're going to use. These pools will persist across benchmarks so it's a one time cost:
+
+For example; to generate 128k 100x100 images using 8 worker threads:
+
+```
+C=8 W=100 H=100 N=128000
+```
+
+This will require an up to date node because workers aren't available in node 10.13, you'll get a warning if that's the case.
+
+The files will be generated in `generated_image_pools/jpg/wxh`. If `C` is not set then it will only add images and assume the existing images are already properly incrementally numbered, without gaps.
+
+If `C` is set (and used) then it will regenerate all images regardless and use that many workers to divide the work.
+
+### Image usage
+
+When you run the benchmark, or generate the random content files, it will first check whether the pools have a sufficient amount of images. If they don't then the image pool is amended (see above).
+
+Once the pool contains enough images for a given type/dimension, the random `.md` files are generated and for each file an image is copied from the pool as well. The copying of images is a lot faster.
+
+It's important to note that the pool will persist between benchamrk runs, while the randomly generated content does not.
+
+### Running the benchmark
+
+Either way, you can start a benchmark run using the following. If the pool doesn't exist or does not have enough images, images will be generated:
+
+```shell
+W=100 H=200 N=1000 M=2 yarn bench
+```
+
+- `N=1000`: instructs the run to build a site of 1000 pages
+- `M=2`: instructs nodejs to use up to 2gb of memory for its long term storage
+- `W=100`: use images that are 100px wide
+- `H=200`: use images that are 200px high
+- `C=8`: (optional) force regenerate the image pool for given size and use 8 worker threads while doing so. Only need to do this once per image type+dimension.
+- Deletes generates files from previous run
+- Generates `N` pages with pseudo-random content, copies one image from pool per page generated
+- Runs `gatsby clean`
+- Runs `gatsby build`
+
+The default `yarn bench` will build 512 pages with 1gb memory.

benchmarks/gabe-fs-markdown-images/gatsby-config.js

@@ -0,0 +1,27 @@
+module.exports = {
+  siteMetadata: {
+    title: `Gatsby FS Markdown Benchmark for Gabe`,
+    description: "A blog like no other blog",
+    author: "Bob the Blogger",
+  },
+  plugins: [
+    `gatsby-transformer-remark`,
+    'gatsby-plugin-image',
+    {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        name: `blog`,
+        path: `${__dirname}/generated_articles`,
+      },
+    },
+    {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        name: `img`,
+        path: `${__dirname}/generated_images`,
+      },
+    },
+    'gatsby-plugin-sharp',
+    'gatsby-transformer-sharp',
+  ],
+}

benchmarks/gabe-fs-markdown-images/gatsby-node.js

@@ -0,0 +1,43 @@
+const path = require(`path`)
+
+const blogPost = path.resolve(`./src/templates/blog-post.js`)
+
+exports.createPages = async ({ graphql, actions }) => {
+  const { createPage } = actions
+
+  const result = await graphql(`
+    query {
+      allMarkdownRemark {
+        nodes {
+          id
+          frontmatter {
+            slug
+            title # used in prev/next
+          }
+        }
+      }
+    }
+  `)
+
+  if (result.errors) {
+    throw result.errors
+  }
+
+  const posts = result.data.allMarkdownRemark.nodes
+
+  posts.forEach(({ id, frontmatter: { slug } }, index) => {
+    const previous = index === posts.length - 1 ? null : posts[index + 1]
+    const next = index === 0 ? null : posts[index - 1]
+
+    createPage({
+      path: slug,
+      component: blogPost,
+      context: {
+        id,
+        slug,
+        previous,
+        next,
+      },
+    })
+  })
+}

benchmarks/gabe-fs-markdown-images/gen.js

@@ -0,0 +1,306 @@
+const fs = require("fs")
+const path = require("path")
+const faker = require(`faker`)
+const genJpg = require("js-image-generator")
+const rimraf = require("rimraf")
+const ProgressBar = require("progress")
+
+const C = parseInt(process.env.C, 10) || 0 // Worker count. If non-zero, shards the image generation and generates N images regardless.
+const N = parseInt(process.env.N, 10) || 100 // Article count
+const W = parseInt(process.env.W, 10) || 640 // Image width
+const H = parseInt(process.env.H, 10) || 326 // Image height
+
+let Worker, isMainThread, parentPort, workerData
+try {
+  // worker_threads is node 10.15 ...
+  ;({
+    Worker,
+    isMainThread,
+    parentPort,
+    workerData,
+  } = require("worker_threads"))
+} catch (e) {
+  if (C > 0) {
+    console.log('')
+    console.warn(
+      "!! Worker threads are supported by nodejs from node 10.15 onwards. Proceeding in single thread mode. Consider upgrading nodejs. !!"
+    )
+    console.log('')
+  }
+}
+
+if (typeof Worker !== "undefined" && !isMainThread) {
+  const { offset, count, width, height } = workerData
+  const imgDir = "./generated_image_pools/jpg/" + width + "x" + height
+  console.log(
+    "Worker; generating",
+    count,
+    "images of",
+    width,
+    "x",
+    height,
+    ". From",
+    offset + ".jpg",
+    "to",
+    offset + count - 1 + ".jpg",
+    "into",
+    imgDir
+  )
+  let i = 0
+  function again() {
+    if (i >= count) {
+      // The end.
+      return
+    }
+
+    genJpg.generateImage(width, height, 80, function (err, image) {
+      fs.writeFileSync(path.join(imgDir, offset + i + ".jpg"), image.data)
+      parentPort.postMessage(1)
+    })
+
+    ++i
+    setImmediate(again)
+  }
+
+  // Need to do this async otherwise any postMessage after the first will be blocked
+  setImmediate(again)
+
+  // This is valid in toplevel in nodejs.
+  return
+}
+
+console.log("Start of gen")
+console.time("End of gen")
+
+const imgDir = "./generated_image_pools/jpg/" + W + "x" + H
+
+if (!fs.existsSync("./generated_image_pools")) {
+  fs.mkdirSync("./generated_image_pools", { recursive: true })
+}
+if (!fs.existsSync(imgDir)) {
+  fs.mkdirSync(imgDir, { recursive: true })
+}
+
+generateImagePool()
+  .then(generateArticles)
+  .then(() => {
+    console.timeEnd("End of gen")
+    console.log()
+  })
+  .catch(e => {
+    throw new Error(e.stack)
+  })
+
+function generateImagePool() {
+  // Image generation is quite expensive so rather than regenerate the images per run, we generate
+  // a static pool of images and copy from that to the correct position when needed. Takes up more
+  // space (not a concern in this context) but is a lot faster.
+  // It literally takes 10 minutes to generate single thread generate 1000 images of default dimensions, 2 hours for 128k of them.
+
+  console.log(
+    "Making sure there are enough",
+    W,
+    "x",
+    H,
+    "jpg images in the pool"
+  )
+
+  if (C > 0 && typeof Worker !== "undefined") {
+    // Ignore existing images of this size and regenerate all of them
+    return forceRegenerateAllWithWorkers()
+  } else {
+    if (C > 0) {
+      console.log("")
+      console.log("RUNNING SINGLE CORE !! Ignoring `C` option because it requires a newer nodejs !! RUNNING SINGLE CORE")
+      console.log("")
+    }
+    // Assume existing images cover entire range 0 to count-1. Only generate count to N-1, single threaded
+    return incrementallyRegenerateNoWorkers()
+  }
+}
+
+function forceRegenerateAllWithWorkers() {
+  rimraf.sync(imgDir)
+  fs.mkdirSync(imgDir, { recursive: true })
+
+  let step = Math.floor(N / C)
+  let lastStep = N - step * (C - 1)
+
+  console.log(
+    "Sharing image generation across",
+    C,
+    "processes. Each process will generate",
+    step,
+    "images in",
+    imgDir
+  )
+
+  function worker(offset, count) {
+    return new Promise((resolve, reject) => {
+      const worker = new Worker(__filename, {
+        workerData: {
+          offset,
+          count,
+          width: W,
+          height: H,
+        },
+      })
+      worker.on("message", () => bar.tick())
+      worker.on("error", reject)
+      worker.on("exit", code => {
+        if (code === 0) {
+          resolve()
+        } else {
+          reject(new Error(`Worker stopped with exit code ${code}`))
+        }
+      })
+    })
+  }
+
+  const workers = []
+  for (let i = 0; i < C; ++i) {
+    workers.push(worker(i * step, i === C - 1 ? lastStep : step))
+  }
+
+  const bar = new ProgressBar(
+    `[:bar] :current/${N} | :percent | :elapsed sec | :rate /s | :eta secs remaining`,
+    {
+      total: N,
+      width: 30,
+      renderThrottle: 50,
+    }
+  )
+
+  return Promise.all(workers)
+}
+
+function incrementallyRegenerateNoWorkers() {
+  const count = fs.readdirSync(imgDir).length
+  if (count === 0 && N > 1000) {
+    if (C === 0) {
+      console.log(
+        "Going to use one core for image generation. Consider using `C=4 W=" +
+          W +
+          " H=" +
+          H +
+          " N=" +
+          N +
+          " node gen.js` to spread the work over 4 workers (or whatever)."
+      )
+      if (typeof Worker === "undefined") {
+        console.log(
+          "This also requires a newer verseion of nodejs (one that supports `worker_threads`)"
+        )
+      }
+    } else {
+      console.log(
+        "This is going to be expensive. Consider using a different node version to generate the pool first."
+      )
+    }
+  } else if (N - count > 1000) {
+    if (C === 0) {
+      console.log(
+        "Going to incrementally fill the pool by " +
+          (N - count) +
+          " images single threaded."
+      )
+      console.log(
+        "Consider using `C=4 W=" +
+          W +
+          " H=" +
+          H +
+          " N=" +
+          N +
+          " node gen.js` to spread the work over 4 workers (or whatever)."
+      )
+    } else {
+      console.log(
+        "This is going to be expensive. Consider using a different node version to regenerate the whole pool first."
+      )
+    }
+  }
+
+  const bar = new ProgressBar(
+    `[:bar] :current/${N} | :percent | :elapsed sec | :rate /s | :eta secs remaining`,
+    {
+      total: N,
+      width: 30,
+      renderThrottle: 100,
+    }
+  )
+
+  bar.tick(Math.min(N, count))
+
+  // This is a controlled environment. Assume that all existing files represent that many images.
+  // If N is larger than that, add that many images to the pool first.
+  for (let i = count; i < N; ++i) {
+    genJpg.generateImage(W, H, 80, function (err, image) {
+      fs.writeFileSync(path.join(imgDir, i + ".jpg"), image.data)
+    })
+    bar.tick()
+  }
+  bar.terminate()
+
+  // At this point the image dir should contain sufficient images to cover the articles
+  // Each image has random noise and should be named "i.jpg", with i from 0 through N-1
+
+  return Promise.resolve()
+}
+
+function generateArticles() {
+  // Assuming there now exists a pool of images of given dimensions, generate an article and copy
+  // an image per article and give it the same name.
+
+  console.log("Generating", N, "articles with one", W, "x", H, "jpg image")
+
+  const bar = new ProgressBar(
+    `[:bar] :current/${N} | :percent | :elapsed sec | :rate /s | :eta secs remaining`,
+    {
+      total: N,
+      width: 30,
+      renderThrottle: 50,
+    }
+  )
+
+  rimraf.sync("./generated_articles")
+  rimraf.sync("./generated_images")
+  fs.mkdirSync("./generated_articles", { recursive: true })
+  fs.mkdirSync("./generated_images", { recursive: true })
+
+  for (let i = 0; i < N; ++i) {
+    const sentence = faker.lorem.sentence()
+    const slug = faker.helpers.slugify(sentence).toLowerCase()
+    fs.writeFileSync(
+      path.join("./generated_articles", slug + ".md"),
+      createArticle(i, sentence, slug)
+    )
+    fs.copyFileSync(
+      path.join(imgDir, i + ".jpg"),
+      path.join("./generated_images", slug + ".jpg")
+    )
+    bar.tick()
+  }
+  bar.terminate()
+
+  console.log("Finished preparing " + N + " articles")
+}
+
+function createArticle(n, sentence, slug) {
+  const desc = faker.lorem.sentence()
+
+  return `---
+articleNumber: ${n}
+title: "${sentence.replace(/"/g, '\\"')}"
+description: "${desc.replace(/"/g, '\\"')}"
+slug: '${slug}'
+date: ${faker.date.recent(1000).toISOString().slice(0, 10)}
+rngImg: ../generated_images/${slug}.jpg
+---
+
+# ${sentence}
+
+> ${desc}
+
+${faker.lorem.paragraphs(2)}
+`
+}

benchmarks/gabe-fs-markdown-images/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "gabe-fs-markdown",
+  "private": true,
+  "description": "Benchmark site for testing baseline markdown perf with individual files per page",
+  "author": "Peter van der Zee <pvdz@github>",
+  "version": "0.1.0",
+  "license": "MIT",
+  "scripts": {
+    "bench": "rm -rf generated_articles generated_images; gatsby clean; N=${N:-512} node gen.js; CI=1 node --max_old_space_size=${M:-2}000 node_modules/.bin/gatsby build",
+    "build": "gatsby build",
+    "clean": "gatsby clean",
+    "develop": "gatsby develop",
+    "format": "prettier --write \"**/*.{js,jsx,json,md}\""
+  },
+  "devDependencies": {
+    "prettier": "2.0.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gatsbyjs/gatsby/tree/master/benchmarks/"
+  },
+  "bugs": {
+    "url": "https://github.com/gatsbyjs/gatsby/issues"
+  },
+  "keywords": [
+    "gatsby",
+    "benchmark",
+    "markdown"
+  ],
+  "dependencies": {
+    "faker": "^4.1.0",
+    "gatsby": "2.31.0-next.0-dev-1610018045350",
+    "gatsby-plugin-image": "*",
+    "gatsby-plugin-sharp": "2.13.0-next.0-dev-1609845921133",
+    "gatsby-source-filesystem": "^2",
+    "gatsby-transformer-remark": "^2",
+    "gatsby-transformer-sharp": "2.11.0-next.0-dev-1609845921133",
+    "js-image-generator": "*",
+    "progress": "*",
+    "react": "^16.12.0",
+    "react-dom": "^16.12.0",
+    "rimraf": "*"
+  }
+}

benchmarks/gabe-fs-markdown-images/src/components/bio.js

@@ -0,0 +1,30 @@
+/**
+ * Bio component that queries for data
+ * with Gatsby's useStaticQuery component
+ *
+ * See: https://www.gatsbyjs.org/docs/use-static-query/
+ */
+
+import React from "react"
+
+const Bio = () => {
+  return (
+    <div
+      style={{
+        display: `flex`,
+        marginBottom: '5px',
+      }}
+    >
+      <p>
+        Written by <strong>Bob</strong> who lives and works in Fan
+        Srancisco building useful things.
+        {` `}
+        <a href={`https://twitter.com/bob`}>
+          You should follow him on Twitter
+        </a>
+      </p>
+    </div>
+  )
+}
+
+export default Bio

benchmarks/gabe-fs-markdown-images/src/components/layout.js

@@ -0,0 +1,72 @@
+import React from "react"
+import { Link } from "gatsby"
+
+class Layout extends React.Component {
+  render() {
+    const { location, title, children } = this.props
+    const rootPath = `${__PATH_PREFIX__}/`
+    let header
+
+    if (location.pathname === rootPath) {
+      header = (
+        <h1
+          style={{
+            marginBottom: '5px',
+            marginTop: 0,
+          }}
+        >
+          <Link
+            style={{
+              boxShadow: `none`,
+              textDecoration: `none`,
+              color: `inherit`,
+            }}
+            to={`/`}
+          >
+            {title}
+          </Link>
+        </h1>
+      )
+    } else {
+      header = (
+        <h3
+          style={{
+            fontFamily: `Montserrat, sans-serif`,
+            marginTop: 0,
+          }}
+        >
+          <Link
+            style={{
+              boxShadow: `none`,
+              textDecoration: `none`,
+              color: `inherit`,
+            }}
+            to={`/`}
+          >
+            {title}
+          </Link>
+        </h3>
+      )
+    }
+    return (
+      <div
+        style={{
+          marginLeft: `auto`,
+          marginRight: `auto`,
+          maxWidth: '75%',
+          padding: `5px`,
+        }}
+      >
+        <header>{header}</header>
+        <main>{children}</main>
+        <footer>
+          © {new Date().getFullYear()}, Built with
+          {` `}
+          <a href="https://www.gatsbyjs.org">Gatsby</a>
+        </footer>
+      </div>
+    )
+  }
+}
+
+export default Layout

benchmarks/gabe-fs-markdown-images/src/pages/404.js

@@ -0,0 +1,30 @@
+import React from "react"
+import { graphql } from "gatsby"
+
+import Layout from "../components/layout"
+
+class NotFoundPage extends React.Component {
+  render() {
+    const { data } = this.props
+    const siteTitle = data.site.siteMetadata.title
+
+    return (
+      <Layout location={this.props.location} title={siteTitle}>
+        <h1>Not Found</h1>
+        <p>You just hit a route that doesn&#39;t exist... the sadness.</p>
+      </Layout>
+    )
+  }
+}
+
+export default NotFoundPage
+
+export const pageQuery = graphql`
+  query {
+    site {
+      siteMetadata {
+        title
+      }
+    }
+  }
+`

benchmarks/gabe-fs-markdown-images/src/pages/index.js

@@ -0,0 +1,69 @@
+import React from "react"
+import { Link, graphql } from "gatsby"
+
+import Bio from "../components/bio"
+import Layout from "../components/layout"
+
+class BlogIndex extends React.Component {
+  render() {
+    const { data } = this.props
+    const siteTitle = data.site.siteMetadata.title
+    const posts = data.allMarkdownRemark.nodes
+
+    return (
+      <Layout location={this.props.location} title={siteTitle}>
+        <Bio />
+        {posts.map(({ frontmatter: { title, slug, date, description } }) => {
+          return (
+            <article key={slug}>
+              <header>
+                <h3
+                  style={{
+                    marginBottom: "5px",
+                  }}
+                >
+                  <Link style={{ boxShadow: `none` }} to={"/" + slug}>
+                    {title}
+                  </Link>
+                </h3>
+                <small>{date}</small>
+              </header>
+              <section>
+                <p
+                  dangerouslySetInnerHTML={{
+                    __html: description,
+                  }}
+                />
+              </section>
+            </article>
+          )
+        })}
+      </Layout>
+    )
+  }
+}
+
+export default BlogIndex
+
+export const pageQuery = graphql`
+  query {
+    site {
+      siteMetadata {
+        title
+      }
+    }
+    allMarkdownRemark(
+      limit: 100
+      sort: { fields: frontmatter___date, order: DESC }
+    ) {
+      nodes {
+        frontmatter {
+          title
+          slug
+          date(formatString: "MMMM DD, YYYY")
+          description
+        }
+      }
+    }
+  }
+`

benchmarks/gabe-fs-markdown-images/src/templates/blog-post.js

@@ -0,0 +1,92 @@
+import React from "react"
+import { Link, graphql } from "gatsby"
+
+import Bio from "../components/bio"
+import Layout from "../components/layout"
+import { GatsbyImage } from "gatsby-plugin-image"
+
+class BlogPostTemplate extends React.Component {
+  render() {
+    const {
+      html,
+      frontmatter: {
+        title,
+        date,
+        rngImg: {
+          childImageSharp: { gatsbyImageData },
+        },
+      },
+    } = this.props.data.markdownRemark
+    const siteTitle = this.props.data.site.siteMetadata.title
+    const { previous, next } = this.props.pageContext
+
+    return (
+      <Layout location={this.props.location} title={siteTitle}>
+        <article>
+          <header>
+            <h1 style={{ marginTop: "5px", marginBottom: 0 }}>{title}</h1>
+            <p style={{ display: `block`, marginBottom: "5px" }}>{date}</p>
+          </header>
+          <section dangerouslySetInnerHTML={{ __html: html }} />
+          <GatsbyImage image={gatsbyImageData} alt="random stuff" />
+          <hr style={{ marginBottom: "5px" }} />
+          <footer>
+            <Bio />
+          </footer>
+        </article>
+
+        <nav>
+          <ul
+            style={{
+              display: `flex`,
+              flexWrap: `wrap`,
+              justifyContent: `space-between`,
+              listStyle: `none`,
+              padding: 0,
+            }}
+          >
+            <li>
+              {previous && (
+                <Link to={"/" + previous.frontmatter.slug} rel="prev">
+                  ← {previous.frontmatter.title}
+                </Link>
+              )}
+            </li>
+            <li>
+              {next && (
+                <Link to={"/" + next.frontmatter.slug} rel="next">
+                  {next.frontmatter.title} →
+                </Link>
+              )}
+            </li>
+          </ul>
+        </nav>
+      </Layout>
+    )
+  }
+}
+
+export default BlogPostTemplate
+
+export const pageQuery = graphql`
+  query BlogPostById($id: String!) {
+    site {
+      siteMetadata {
+        title
+      }
+    }
+    markdownRemark(id: { eq: $id }) {
+      html
+      frontmatter {
+        title
+        rngImg {
+          childImageSharp {
+            gatsbyImageData
+            #  gatsbyImageData(layout: FIXED, width: 125, height: 125)
+          }
+        }
+        date(formatString: "MMMM DD, YYYY")
+      }
+    }
+  }
+`

benchmarks/gabe-fs-markdown-images/static/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Disallow:

benchmarks/source-strapi/README.md

@@ -8,6 +8,6 @@ Create a .env file from the template:
 
 Update data:
 
-```sh
+```shell
 yarn date-update
 ```

docs/contributing/docs-and-blog-components.md

@@ -354,4 +354,4 @@ plugins: [
 ]
 ```
 
-Line numbers and line highlighting can be added to code blocks as well, and is explained in detail in the [`gatsby-remark-prismjs` README](/packages/gatsby-remark-prismjs/?=remark#optional-add-line-highlighting-styles).
+Line numbers and line highlighting can be added to code blocks as well, and is explained in detail in the [`gatsby-remark-prismjs` README](/plugins/gatsby-remark-prismjs/?=remark#optional-add-line-highlighting-styles).

docs/contributing/gatsby-style-guide.md

@@ -29,7 +29,7 @@ examples:
 - [Reference guide overviews](/docs/styling/)
 - [Recipes](/docs/recipes/)
 - [Tutorials](/docs/tutorial/part-one/)
-- [Plugin README](/packages/gatsby-source-filesystem/)
+- [Plugin README](/plugins/gatsby-source-filesystem/)
 - [Starter README](https://github.com/gatsbyjs/gatsby-starter-default)
 
 Please see the [Docs templates](/contributing/docs-templates/) for guidelines on how to format the above kinds of documents, as well as tips for different types of guide articles.

docs/contributing/how-to-make-a-reproducible-test-case.md

@@ -17,7 +17,7 @@ A reproducible test case is a great way to share a specific environment that cau
 ## Steps to create a reproducible test case
 
 - Create a new Gatsby site with a starter, the official `hello-world` starter is a great 'barebones' starting point here: `gatsby new bug-repro https://github.com/gatsbyjs/gatsby-starter-hello-world`
-- Add any Gatsby plugins that relate to the issue. For example, if you're having problems with Gatsby MDX you should install and configure [`gatsby-plugin-mdx`](/packages/gatsby-plugin-mdx/). Only add plugins that are needed to demonstrate the problem.
+- Add any Gatsby plugins that relate to the issue. For example, if you're having problems with Gatsby MDX you should install and configure [`gatsby-plugin-mdx`](/plugins/gatsby-plugin-mdx/). Only add plugins that are needed to demonstrate the problem.
 - Add the code needed to recreate the error you've seen.
 - Publish the code (your GitHub account is a good place to do this) and then link to it when [creating an issue](/contributing/how-to-file-an-issue/).
 

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

@@ -5,7 +5,7 @@ issue: https://github.com/gatsbyjs/gatsby/issues/21599
 
 ## Near-perfect example of a plugin README
 
-[`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/)
+[`gatsby-source-filesystem`](/plugins/gatsby-source-filesystem/)
 
 ```markdown
 ## Description

docs/contributing/translation/sync-guide.md

@@ -126,7 +126,7 @@ The only necessary change is to ensure the translated content carries over these
 These changes involve updating the URL of a link:
 
 ```diff
-- Please see our [plugins page](/packages).
+- Please see our [plugins page](/plugins).
 + Please see our [plugins page](/plugins).
 ```
 

docs/docs/add-page-metadata.md

@@ -8,7 +8,7 @@ Adding metadata to pages (such as a title or description) is key in helping sear
 
 [React Helmet](https://github.com/nfl/react-helmet) is a package that provides a React component interface for you to manage your [document head](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head).
 
-Gatsby's [react helmet plugin](/packages/gatsby-plugin-react-helmet/) provides drop-in support for server rendering data added with React Helmet. Using the plugin, attributes you add to React Helmet will be added to the static HTML pages that Gatsby builds.
+Gatsby's [react helmet plugin](/plugins/gatsby-plugin-react-helmet/) provides drop-in support for server rendering data added with React Helmet. Using the plugin, attributes you add to React Helmet will be added to the static HTML pages that Gatsby builds.
 
 ## Using `React Helmet` and `gatsby-plugin-react-helmet`
 

docs/docs/adding-a-shopping-cart-with-snipcart.md

@@ -10,7 +10,7 @@ Combine it with a source of products (like a CMS or an e-commerce platform such
 
 To get started, you'll need to have the following set up:
 
-- A Gatsby site with [`gatsby-plugin-snipcart`](/packages/gatsby-plugin-snipcart/) installed
+- A Gatsby site with [`gatsby-plugin-snipcart`](/plugins/gatsby-plugin-snipcart/) installed
 - A [Snipcart](https://snipcart.com/) account
 - A Snipcart test API key
 - A list of products to sell
@@ -186,7 +186,7 @@ The following quote is from the Snipcart [payment gateway page](https://app.snip
 ## Other resources
 
 - [Build an E-commerce Site with Gatsby, DatoCMS, and Snipcart](/tutorial/e-commerce-with-datocms-and-snipcart/) tutorial
-- [`gatsby-plugin-snipcart`](/packages/gatsby-plugin-snipcart/)
+- [`gatsby-plugin-snipcart`](/plugins/gatsby-plugin-snipcart/)
 - [OneShopper Gatsby starter](/starters/rohitguptab/OneShopper/)
 - Reference guide on [sourcing from Etsy](/docs/sourcing-from-etsy/)
 - Reference guide on [processing payments with Stripe](/docs/how-to/adding-common-features/processing-payments-with-stripe/)

docs/docs/adding-search-with-algolia.md

@@ -191,7 +191,7 @@ The guide will use the following frameworks:
 
 - [React InstantSearch](https://community.algolia.com/react-instantsearch), a component library provided by Algolia for easily building search interfaces.
 - [Algolia Search](https://www.npmjs.com/package/algoliasearch) provides the API client for calling Algolia.
-- [Styled Components](https://styled-components.com) for embedding the CSS in the code, integrated using the [Gatsby styled component plugin](/packages/gatsby-plugin-styled-components/).
+- [Styled Components](https://styled-components.com) for embedding the CSS in the code, integrated using the [Gatsby styled component plugin](/plugins/gatsby-plugin-styled-components/).
 - [Styled Icons](https://styled-icons.js.org/) provides the magnifying glass icon for the search bar.
 
 Styled Components can also be replaced by any other CSS solution you prefer.

docs/docs/api-specification.md

@@ -21,13 +21,13 @@ Plugins can extend Gatsby in many ways:
 - Adding things to the rendered HTML (e.g. meta tags, analytics JS snippets like Google Analytics)
 - Writing out things to build directory based on site data (e.g. service worker, sitemap, RSS feed)
 
-A single plugin can use multiple APIs to accomplish its purpose. E.g. the plugin for the CSS-in-JS library [Glamor](/packages/gatsby-plugin-glamor/):
+A single plugin can use multiple APIs to accomplish its purpose. E.g. the plugin for the CSS-in-JS library [Glamor](/plugins/gatsby-plugin-glamor/):
 
 1. modifies the webpack config to add its plugin
 2. adds a Babel plugin to replace React's default createElement
 3. modifies server rendering to extract out the critical CSS for each rendered page and inline the CSS in the `<head>` of that HTML page.
 
-Plugins can also depend on other plugins. [The Sharp plugin](/packages/gatsby-plugin-sharp/) exposes a number of high-level APIs for transforming images that several other Gatsby image plugins depend on. [gatsby-transformer-remark](/packages/gatsby-transformer-remark/) does basic markdown->HTML transformation but exposes an API to allow other plugins to intervene in the conversion process e.g. [gatsby-remark-prismjs](/packages/gatsby-remark-prismjs/) which adds highlighting to code blocks.
+Plugins can also depend on other plugins. [The Sharp plugin](/plugins/gatsby-plugin-sharp/) exposes a number of high-level APIs for transforming images that several other Gatsby image plugins depend on. [gatsby-transformer-remark](/plugins/gatsby-transformer-remark/) does basic markdown->HTML transformation but exposes an API to allow other plugins to intervene in the conversion process e.g. [gatsby-remark-prismjs](/plugins/gatsby-remark-prismjs/) which adds highlighting to code blocks.
 
 Transformer plugins are decoupled from source plugins. Transformer plugins look at the media type of new nodes created by source plugins to decide if they can transform it or not. Which means that a markdown transformer plugin can transform markdown from any source without any other configuration e.g. from a file, a code comment, or external service like Trello which supports markdown in some of its data fields.
 

docs/docs/building-an-e-commerce-site.md

@@ -2,7 +2,7 @@
 title: Building an E-commerce Site
 ---
 
-The speed and performance of sites built with Gatsby make it a great tool for building e-commerce sites. There are existing plugins for connecting services like [Shopify](/packages/gatsby-source-shopify/) and [Snipcart](/packages/gatsby-plugin-snipcart/) to Gatsby, and this section contains reference guides to help get things setup.
+The speed and performance of sites built with Gatsby make it a great tool for building e-commerce sites. There are existing plugins for connecting services like [Shopify](/plugins/gatsby-source-shopify/) and [Snipcart](/plugins/gatsby-plugin-snipcart/) to Gatsby, and this section contains reference guides to help get things setup.
 
 To see examples of e-commerce sites built with Gatsby, check out the [showcase](/showcase/?filters%5B0%5D=E-commerce).
 

docs/docs/building-an-ecommerce-site-with-shopify.md

@@ -17,7 +17,7 @@ If you are already comfortable with Gatsby and Shopify, you might want to check
 
 1. If you do not already have one ready, [create a Gatsby site](/docs/quick-start).
 
-2. Install the [`gatsby-source-shopify`](/packages/gatsby-source-shopify/) plugin and [`shopify-buy`](https://github.com/Shopify/js-buy-sdk) package.
+2. Install the [`gatsby-source-shopify`](/plugins/gatsby-source-shopify/) plugin and [`shopify-buy`](https://github.com/Shopify/js-buy-sdk) package.
 
 ```shell
 npm install gatsby-source-shopify shopify-buy

docs/docs/caching.md

@@ -44,7 +44,7 @@ How you setup your caching depends on how you host your site. We encourage peopl
 
 The following plugins have been created:
 
-- [gatsby-plugin-netlify](/packages/gatsby-plugin-netlify/)
+- [gatsby-plugin-netlify](/plugins/gatsby-plugin-netlify/)
 - [gatsby-plugin-s3](https://github.com/jariz/gatsby-plugin-s3)
 
 When deploying with Vercel, follow the instructions in the [Vercel documentation](https://vercel.com/guides/deploying-gatsby-with-vercel#bonus:-cache-your-gatsby-assets).

docs/docs/conceptual/gatsby-for-ecommerce.md

@@ -0,0 +1,47 @@
+---
+title: Using Gatsby For E-commerce
+---
+
+Businesses selling products online typically need a variety of software to support their experience. At a minimum, their website needs product pages, product catalog navigation, a shopping cart, and checkout.
+
+Most have additional functionality like customer account creation, promotions, discounts, and loyalty, customer reviews, tax calculation, user tracking via analytics, and content personalization.
+
+The website functions because these front-end capabilities integrate with a wide swath of software on the backend, such as inventory management, order fulfillment, accounting and business analytics, and customer engagement via email.
+
+### Choosing a main e-commerce platform
+
+Most businesses choose a central e-commerce platform as their source of truth for these functionality. Some businesses choose to run entirely on these platforms, which can be quicker to get started with but lock you in to their choices for website creation (eg Liquid Templates for Shopify).
+
+If you're using or considering Gatsby, your organization is likely optimizing for specific properties of your website (such as performance, development environment, design, user experience, and security) and are therefore considering a "JAMstack", "decoupled" or "content mesh" architecture.
+
+In this case, your options are likely between a technologically forward e-commerce vendor with headless capabilities, such as Shopify or BigCommerce, or a new, specialized JAMStack e-commerce vendor, like Elastic Path, Snipcart, Nacelle, or CommerceLayer. All of these have out-of-the box Gatsby integrations.
+
+### Choosing additional content systems
+
+Once an organization selects a main e-commerce platform, it may also want or need other content stores that will get pulled into the website. They might choose a CMS like Contentful for complex content modelling, or Wordpress for blog content authoring. They might choose Yotpo for customer reviews or Salsify for product information management.
+
+### Why organizations build e-commerce sites with Gatsby
+
+Organizations looking for a JAMStack e-commerce site that go with Gatsby typically do so for a combination of three reasons: they want to embrace a modern development framework (React), they want to optimize performance, and they want a web framework that’s already integrated with the systems they’re using (via Gatsby’s plugin system and pre-built integrations).
+
+From a conversion perspective, Gatsby’s lightning-fast performance is a huge win: Gatsby automates code splitting, image optimization, inlining critical styles, lazy-loading, prefetching resources, and more to ensure your site is fully optimized.
+
+And with Gatsby’s pre-built integrations, it can pull data in from all of these sources (Shopify, plus Wordpress, Contentful, Yotpo, etc) and make it available for the React components.
+
+### Specific e-commerce development considerations
+
+E-commerce tends to have a number of specific requirements. When building a Gatsby site (or other decoupled/JAMStack site, for that matter) sourced from an ecommerce backend like Shopify, developers will typically have to think through a few additional touchpoints between the systems:
+
+- **Persisting a cart across site pages and between sessions** (ie, if the user closes their browser and reopens it tomorrow, the items should still be there). This can handled either through local-storage or through the shopify-buy JS library.
+- **Product search** can be done client-side if the SKU count is small enough to store all products in a global state. Alternatively, it can be handled through the e-commerce provider’s search features, or if those aren’t robust enough, a third-party search provider like Algolia.
+- **Surfacing price adjustments** like tax, shipping, discounts/promos to the user while browsing the site. Different e-commerce solutions provide different levels of API access to these objects.
+- **Handling checkout.** In order to comply with PCI regulations around storing credit card information, e-commerce providers typically exert strong control over the "buy" or "checkout" experience. Shopify requires all checkout flows using their platform to use their hosted checkout pages, though it's common to wrap them in a subdomain of the main site (eg the Gatsby/Shopify site [strivectin.com](strivectin.com] wraps a `myshopify.com` URL under a `shop.strivectin.com` URL for checkout).
+- **Handling account pages.** Again, many sites choose to wrap their e-commerce provider’s account pages under their own domain.
+
+Additional resources:
+
+- [What is Headless Commerce?](https://www.bigcommerce.com/articles/headless-commerce/#unlocking-flexibility-examples-of-headless-commerce-in-action), an overview from BigCommerce.
+- [Gatsby Shopify Starter](https://github.com/AlexanderProd/gatsby-shopify-starter)
+- Sell Things Fast With Gatsby and Shopify by Trevor Harmon [blog post](https://thetrevorharmon.com/blog/sell-things-fast-with-gatsby-and-shopify), [video](https://www.youtube.com/watch?v=tUtuGAFOjYI&t=16m59s) and [Github repo](https://github.com/thetrevorharmon/sell-things-fast/)
+- [Gatsby Use Cases: E-commerce](https://www.gatsbyjs.com/use-cases/e-commerce)
+- [Best e-commerce solutions for Jamstack websites](https://bejamas.io/blog/jamstack-ecommerce/) from the Bejamas blog.

docs/docs/conceptual/graphql-concepts.md

@@ -182,7 +182,7 @@ See the full list of formatting options by viewing our [GraphQL reference page](
 
 ### Markdown
 
-Gatsby has _transformer_ plugins which can transform data from one form to another. A common example is markdown. If you install [`gatsby-transformer-remark`](/packages/gatsby-transformer-remark/), then in your queries, you can specify if you want the transformed HTML version instead of markdown:
+Gatsby has _transformer_ plugins which can transform data from one form to another. A common example is markdown. If you install [`gatsby-transformer-remark`](/plugins/gatsby-transformer-remark/), then in your queries, you can specify if you want the transformed HTML version instead of markdown:
 
 ```graphql
 markdownRemark {
@@ -192,9 +192,9 @@ markdownRemark {
 
 ### Images
 
-Gatsby has rich support for processing images. Responsive images are a big part of the modern web and typically involve creating 5+ sized thumbnails per photo. With Gatsby's [`gatsby-transformer-sharp`](/packages/gatsby-transformer-sharp/), you can _query_ your images for responsive versions. The query automatically creates all the needed responsive thumbnails and returns `src` and `srcSet` fields to add to your image element.
+Gatsby has rich support for processing images. Responsive images are a big part of the modern web and typically involve creating 5+ sized thumbnails per photo. With Gatsby's [`gatsby-transformer-sharp`](/plugins/gatsby-transformer-sharp/), you can _query_ your images for responsive versions. The query automatically creates all the needed responsive thumbnails and returns `src` and `srcSet` fields to add to your image element.
 
-Combined with a special Gatsby image component, [gatsby-image](/packages/gatsby-image/), you have a very powerful set of primitives for building sites with images.
+Combined with a special Gatsby image component, [gatsby-image](/plugins/gatsby-image/), you have a very powerful set of primitives for building sites with images.
 
 This is what a component using `gatsby-image` looks like:
 

docs/docs/conceptual/making-your-site-accessible.md

@@ -49,7 +49,7 @@ For more on supported rules, check out the docs for [`eslint-plugin-jsx-a11y`](h
 }
 ```
 
-Note: Including a local `.eslintrc` file will [override](/docs/how-to/custom-configuration/eslint/#configuring-eslint) all of Gatsby's default linting and disable the built-in `eslint-loader`, meaning your tweaked rules won't make it to your browser's developer console or your terminal window but will still be displayed if you have ESLint plugins enabled in your IDE. If you would like to change this behavior and make sure the `eslint-loader` pulls in your customizations, you'll need to enable the loader yourself. One way to do this is by using the Community plugin [`gatsby-plugin-eslint`](/packages/gatsby-plugin-eslint/). Additionally, if you would still like to take advantage of some subset of the default [ESLint config Gatsby ships with](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/eslint-config.ts), you'll need to copy them manually to your local `.eslintrc` file.
+Note: Including a local `.eslintrc` file will [override](/docs/how-to/custom-configuration/eslint/#configuring-eslint) all of Gatsby's default linting and disable the built-in `eslint-loader`, meaning your tweaked rules won't make it to your browser's developer console or your terminal window but will still be displayed if you have ESLint plugins enabled in your IDE. If you would like to change this behavior and make sure the `eslint-loader` pulls in your customizations, you'll need to enable the loader yourself. One way to do this is by using the Community plugin [`gatsby-plugin-eslint`](/plugins/gatsby-plugin-eslint/). Additionally, if you would still like to take advantage of some subset of the default [ESLint config Gatsby ships with](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/eslint-config.ts), you'll need to copy them manually to your local `.eslintrc` file.
 
 This is a start to testing for accessibility: [further recommendations](#how-to-improve-accessibility) can be found below.
 

docs/docs/conceptual/overview-of-the-gatsby-build-process.md

@@ -56,7 +56,7 @@ success onPostBootstrap - 0.130 s
 info bootstrap finished - 3.674 s
 ⠀
 success run static queries - 0.057 s — 3/3 89.08 queries/second
-success run page queries - 0.033 s — 5/5 347.81 queries/second
+success run page queries - 0.026s - 3/3 114.85/s
 success start webpack server - 1.707 s — 1/1 6.06 pages/second
 ```
 
@@ -136,8 +136,9 @@ success onPostBootstrap - 0.130 s
 info bootstrap finished - 3.674 s
 ⠀
 success run static queries - 0.057 s — 3/3 89.08 queries/second
-success run page queries - 0.033 s — 5/5 347.81 queries/second
+- success run page queries - 0.033 s — 5/5 347.81 queries/second
 - success start webpack server - 1.707 s — 1/1 6.06 pages/second
++ success run page queries - 0.026s - 3/3 114.85/s
 + success Generating image thumbnails — 6/6 - 1.059 s
 + success Building production JavaScript and CSS bundles - 8.050 s
 + success Rewriting compilation hashes - 0.021 s
@@ -151,6 +152,8 @@ There is only one difference in the bootstrap phase where HTML and CSS is delete
 
 By omitting these later steps, `gatsby develop` can speed up your ability to make live edits without page reloads using features like [hot module replacement](/docs/glossary#hot-module-replacement). It also saves time with the more CPU intensive processes that aren't necessary to perform in rapid development.
 
+There is also a difference in the number of page queries that will run. `gatsby develop` will run at most 3 page queries (index page, actual 404 and develop 404) initially. The rest of the queries will run when they are needed (when the browser requests them). In contrast, `gatsby build` will run page queries for every page that doesn't have cached and up to date results already.
+
 A [cache](/docs/glossary#cache) is also used to detect changes to `gatsby-*.js` files (like `gatsby-node.js`, or `gatsby-config.js`) or dependencies. It can be cleared manually with the `gatsby clean` command to work through issues caused by outdated references and a stale cache.
 
 ## What happens when you run `gatsby build`?

docs/docs/conceptual/plugins-themes-and-starters.md

@@ -92,7 +92,7 @@ Plugins and themes both allow options to be passed in when installed in the plug
 
 Theme [shadowing](/docs/how-to/plugins-and-themes/shadowing/) exists to allow users to override or otherwise extend individual components provided by a theme. For example, a plugin or theme can provide a specific path to `gatsby-config` so the plugin knows where to build pages from, but the user wouldn't be able adjust _how_ those pages are built, only from what path. Theme shadowing allows users to replace a file with their own version of it, allowing them to rewrite that logic to use the path in a different way.
 
-An example of a plugin that uses shadowing is [`gatsby-plugin-theme-ui`](/packages/gatsby-plugin-theme-ui/?=theme-ui#customizing-the-theme) which allows you to shadow a theme file to use in your own theme.
+An example of a plugin that uses shadowing is [`gatsby-plugin-theme-ui`](/plugins/gatsby-plugin-theme-ui/?=theme-ui#customizing-the-theme) which allows you to shadow a theme file to use in your own theme.
 
 Starters aren't capable of shadowing (and they don't need to be), because a user of a starter can adjust any file by editing it directly.
 
@@ -104,7 +104,7 @@ Themes are intended to abstract several plugins into one, by making a `gatsby-co
 
 Custom components are most traditionally distributed as packages in the React ecosystem. Components don't need to hook into the Gatsby build system, so if shipped with a plugin they don't need to be included in a `gatsby-config`'s plugin array. This is the case with `gatsby-image` which is a React component. It doesn't need to be included in the plugins array because it is merely a component.
 
-Some plugins ship with components you can use in a Gatsby site. An example is the [`<OutboundLink />` component from `gatsby-plugin-google-analytics`](/packages/gatsby-plugin-google-analytics/?=#outboundlink-component). Other plugins, like [`gatsby-plugin-react-helmet`](/packages/gatsby-plugin-react-helmet), require you to install components from other libraries.
+Some plugins ship with components you can use in a Gatsby site. An example is the [`<OutboundLink />` component from `gatsby-plugin-google-analytics`](/plugins/gatsby-plugin-google-analytics/?=#outboundlink-component). Other plugins, like [`gatsby-plugin-react-helmet`](/plugins/gatsby-plugin-react-helmet), require you to install components from other libraries.
 
 Themes by convention are more suited to ship with components that could then be shadowed for customization.
 

docs/docs/conceptual/security-in-gatsby.md

@@ -148,8 +148,8 @@ Sometimes in your Gatsby website, you will need display sensitive data or handle
 
 Content Security Policy is a security layer added in web applications to detect and prevent attacks, e.g. the XSS attack mentioned above.
 
-To add it to your Gatsby website, add [gatsby-plugin-csp](/packages/gatsby-plugin-csp/) to your `gatsby-config.js` with the desired configuration. Note that
-currently there is a [compatibility issue](https://github.com/gatsbyjs/gatsby/issues/10890) between [gatsby-plugin-csp](/packages/gatsby-plugin-csp/) and other plugins that generate hashes in inline styles, including [gatsby-image](/packages/gatsby-image).
+To add it to your Gatsby website, add [gatsby-plugin-csp](/plugins/gatsby-plugin-csp/) to your `gatsby-config.js` with the desired configuration. Note that
+currently there is a [compatibility issue](https://github.com/gatsbyjs/gatsby/issues/10890) between [gatsby-plugin-csp](/plugins/gatsby-plugin-csp/) and other plugins that generate hashes in inline styles, including [gatsby-image](/plugins/gatsby-image).
 
 > Note that not all browsers support CSP, check [can-i-use](https://caniuse.com/#feat=mdn-http_headers_csp_content-security-policy) for more information.
 

docs/docs/conceptual/using-gatsby-image.md

@@ -0,0 +1,85 @@
+---
+title: Why Gatsby's Automatic Image Optimizations Matter
+---
+
+The web has come a long way since 1995, when `<img src="....">` syntax was invented. Our visual standards for what we've come to expect have risen -- a lot.
+
+When visiting new pages, users expect pages to load near-instantly, with a smooth experience. A delay of 100ms is associated with a 3% increased bounce rate.
+
+One important part of overall page loading experience is image loading. There are three basic principles of delivering an optimal image loading experience:
+
+- **Fetch "above the fold" images immediately; delay other work**. This means doing the work necessary for showing users the images they'll see on page load -- and _only_ that work, to avoid resource congestion.
+
+- **Provide a placeholder during image fetch**. "Progressive images" are image placeholders -- previews of a full image that hold its place during page load time.
+
+- **Minimize image file size to reduce request roundtrip time.** There are a number of ways, from cropping overly large images, to using newer file types, to reduce image file size.
+
+We built Gatsby Image to provide these things -- a [higher-level building block](https://www.gatsbyjs.com/docs/conceptual/gatsby-core-philosophy/#construct-new-higher-level-web-building-blocks) that has the richness users expect, with the API simplicity developers love (and without maintaining your own image processing pipeline!).
+
+We provide a [detailed guide on using Gatsby Image](docs/how-to/images-and-media/using-gatsby-image/) in the How To section of this documentation. Here, we walk through the question of why these benefits matter, from a user's perspective, and why providing them without Gatsby Image (or something similar) can be difficult.
+
+## Fetch above-the-fold images immediately
+
+### Avoid hydration lag for React apps
+
+When you're building a website with React you face a bit of a catch-22 for optimizing image loads. If you send over React Javscript files to be evaluated by the browser (client-side rendering), you can't start loading images until the browser evaluates all of the Javascript to figure out what images you want to load. On the other hand, if you evaluate the Javascript on the server and then send over the HTML (server-side rendering), then the initial request will take longer to load while it waits for this server-side evaluation.
+
+Because Gatsby does server rendering during the build process _(rather than when a user is loading the page)_ a Gatsby site will return HTML immediately without waiting for server rendering, and then the client's browser can start loading images as soon as it receives the HTML. Depending on the size of the app, this could save anything from a few hundred milliseconds to a few seconds.
+
+### Delay offscreen images
+
+As important as loading critical images immediately is _not_ loading non-critical images. Loading images is a lot of work for browsers and eagerly loading offscreen images on initial page load [can slow down overall page interactivity](https://web.dev/offscreen-images/).
+
+There are a couple of important pieces here.
+
+First, automatically detect which images should be lazily loaded. While development teams _may_ do this manually, it may not even be in their control (for example, if content including images is coming from a CMS).
+
+Second, actually implement lazy loading. This is supported natively for many browsers, but right now, [almost 30% of users are on browsers](https://caniuse.com/loading-lazy-attr) that don't support it.
+
+Gatsby generates the native component for use in browsers that can use it, and creates the same effect manually for browsers than haven't yet implemented lazy loading through leveraging the IntersectionObserver API.
+
+## Image placeholders
+
+Studies have shown that progressive images cause users to perceive a faster page load. This is because they deliver a gentler, more gradual experience -- a gradual fade-in rather than a jarring frame-to-fame switch from empty background to present image.
+
+### Hold position, prevent reflow
+
+One of the challenges when images load alongside text is preventing what's known as "browser reflow". That is the jankiness that results when an image appears next to text, bumping the text to the right, or above text, bumping it below.
+
+When a browser doesn't know how big an image is going to be, either because the width and height haven't been defined, or because it's variable due to responsive images, reflow can happen, which both impacts performance (by blocking the main thread of execution), and results in a jarring visual effect.
+
+### Gradual color transition
+
+In addition, when an image appears, it goes from blank background to fully there from one frame to another. This can also be visually jarring. Like css has a `transition` prop to help position shifts feel gradual, images feel more aesthetically pleasing when they have placeholders.
+
+Gatsby Image's will hold the spot for your image automatically when you specify `width` prop, and depending on your preference, will provide a background -- blurred, a background color, or traced SVG, while the image loads.
+
+![Gatsby Image Gradual Transition](../images/gatsby-image-gif.gif)
+
+## Minimize image file size
+
+There are a number of ways to minimize image file size. Below are three of the most common, roughly in order of increasing complexity.
+
+### Cropping and compressing overly large images
+
+A common problem in larger projects is that images are uploaded into a CMS by content operations personnel by teams that may be less aware of appropriate web image sizes and formats.
+
+For example, a support staff member may take a 1600x2000 pixel screenshot, save it as a PNG, and upload it alongside a helpdesk article. While this is a quite reasonable action, it may degrade page performance significantly. If the article has a 800px maximum width, a 640 x 800 pixel JPG would have displayed at the same quality but a tenth of the size; the extra weight may delay page load by a second or two.
+
+You can solve this on your own via creating and maintaining a custom image processing pipeline, perhaps during CI/CD, to resize. However, that requires writing, and then maintaining, custom code. Gatsby Image solves this out of the box; if you use the `width` or `maxWidth` prop, Gatsby Image will automatically resize larger underlying assets.
+
+### Generating "responsive images" for different device sizes
+
+Different devices have different screen sizes and resolutions, which means it may make sense to send smaller (or larger) objects.
+
+Sending an image with a width of 800px to a mobile phone with a 400px wide screen means that you are sending unnecessary data over the wire that will, again, delay page load, cause visitors to bounce, and hurt conversions.
+
+Conversely, some laptops, like Macbook Pros, have a higher pixel-to-density ratio, so need "2x"-size images.
+
+In order to support responsive images, you need to do the image processing beforehand, as well as generate the markup necessary. Gatsby Image has a `fluid` option that will transform images with a relatively straightforward API.
+
+### Better compression
+
+The new [WebP image](https://developers.google.com/speed/webp) standard reduces image size by 25-35% for modern browsers. It's possible to support this standard, but you also need to fall back for older browsers that don't support this, which without framework support adds additional complexity.
+
+Gatsby supports WebP out of the box as a setting on Gatsby Image.

docs/docs/creating-a-source-plugin.md

@@ -305,7 +305,7 @@ This loose coupling between the data source and the transformer plugins allow Ga
 
 #### Sourcing and optimizing images from remote locations
 
-A common use case for source plugins is pulling images from a remote location and optimizing them for use with [Gatsby Image](/packages/gatsby-image/). An API may return a URL for an image on a CDN, which could be further optimized by Gatsby at build time.
+A common use case for source plugins is pulling images from a remote location and optimizing them for use with [Gatsby Image](/plugins/gatsby-image/). An API may return a URL for an image on a CDN, which could be further optimized by Gatsby at build time.
 
 This can be achieved by the following steps:
 

docs/docs/creating-and-modifying-pages.md

@@ -207,7 +207,7 @@ trailing slashes.
 To do this, in your site's `gatsby-node.js` add code similar to the following:
 
 _Note: There's also a plugin that will remove all trailing slashes from pages automatically:
-[gatsby-plugin-remove-trailing-slashes](/packages/gatsby-plugin-remove-trailing-slashes/)_.
+[gatsby-plugin-remove-trailing-slashes](/plugins/gatsby-plugin-remove-trailing-slashes/)_.
 
 _Note: If you need to perform an asynchronous action within `onCreatePage` you can return a promise or use an `async` function._
 

docs/docs/creating-prefixed-404-pages-for-different-languages.md

@@ -58,4 +58,4 @@ exports.onCreatePage = async ({ page, actions }) => {
 
 Now, whenever Gatsby creates a page, it will check if the page is a localized 404 with a path in the format of `/XX/404/`. If this is the case, then it will get the language code, and match all paths starting with this code, apart from other valid paths. This means that whenever you visit a non-existent page on your site, whose path starts with `/en/` or `/de/` (e.g. `/en/this-does-not-exist`), your localized 404 page will be displayed instead.
 
-For best results, you should configure your server to serve these 404 pages in the same manner - i.e. for `/en/<non existent path>`, your server should serve the page `/en/404/`. Otherwise, you'll briefly see the default 404 page until the Gatsby runtime loads. If you're using Netlify, you can use [`gatsby-plugin-netlify`](/packages/gatsby-plugin-netlify/) to do this automatically. Note that you should still create a default 404 page (usually at `src/pages/404.js`) to handle non-prefixed paths, e.g. `https://example.com/this-does-not-exist`.
+For best results, you should configure your server to serve these 404 pages in the same manner - i.e. for `/en/<non existent path>`, your server should serve the page `/en/404/`. Otherwise, you'll briefly see the default 404 page until the Gatsby runtime loads. If you're using Netlify, you can use [`gatsby-plugin-netlify`](/plugins/gatsby-plugin-netlify/) to do this automatically. Note that you should still create a default 404 page (usually at `src/pages/404.js`) to handle non-prefixed paths, e.g. `https://example.com/this-does-not-exist`.

docs/docs/custom-html.md

@@ -30,7 +30,7 @@ Note: the various props that are rendered into pages _are_ required e.g.
 Anything you render in the `html.js` component will _not_ be made "live" in
 the client like other components. If you want to dynamically update your
 `<head>` we recommend using
-[React Helmet](/packages/gatsby-plugin-react-helmet/)
+[React Helmet](/plugins/gatsby-plugin-react-helmet/)
 
 ## Inserting HTML into the `<footer>`
 

docs/docs/data-fetching.md

@@ -16,7 +16,7 @@ Compiling pages at build time is useful when your website content won't change o
 
 ## Combining build time and client runtime data
 
-To illustrate a combination of build time and client runtime data, this guide uses code from a small [example site]. It uses the [`gatsby-source-graphql`](/packages/gatsby-source-graphql/) plugin to fetch data from GitHub's GraphQL API at build time for static content like the name and URL to a repository, and the [`fetch` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to retrieve more dynamic data from the GitHub API on the [client-side](/docs/glossary#client-side) like star counts when the page loads in the browser.
+To illustrate a combination of build time and client runtime data, this guide uses code from a small [example site]. It uses the [`gatsby-source-graphql`](/plugins/gatsby-source-graphql/) plugin to fetch data from GitHub's GraphQL API at build time for static content like the name and URL to a repository, and the [`fetch` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to retrieve more dynamic data from the GitHub API on the [client-side](/docs/glossary#client-side) like star counts when the page loads in the browser.
 Reasons to fetch certain data at build time vs. client runtime will vary, but in this example the repo's name and URL are much less likely to change between builds of the site. The repo's star counts, on the other hand, are likely to change often and would benefit from a client-side request to the GitHub API to stay current between static site builds.
 
 > Check out the code from the [full example here](https://github.com/gatsbyjs/gatsby/tree/master/examples/data-fetching).

docs/docs/files-gatsby-looks-for-in-a-plugin.md

@@ -16,7 +16,7 @@ All files are optional unless specifically marked as required.
     - if `version` isn’t set, an MD5 hash of the `gatsby-*` file contents is used to invalidate the cache
     - omitting the `version` field is recommended for local plugins
   - `keywords` is used to make your plugin discoverable
-    - plugins published on the npm registry should have `gatsby` and `gatsby-plugin` in the `keywords` field to be added to the [Plugin Library](/packages/)
+    - plugins published on the npm registry should have `gatsby` and `gatsby-plugin` in the `keywords` field to be added to the [Plugin Library](/plugins/)
 - `gatsby-browser.js` — usage details are in the [browser API reference](/docs/reference/config-files/gatsby-browser/)
 - `gatsby-node.js` — usage details are in the [Node API reference](/docs/reference/config-files/gatsby-node/)
 - `gatsby-ssr.js` — usage details are in the [SSR API reference](/docs/reference/config-files/gatsby-ssr/)

docs/docs/gatsby-internals-terminology.md

@@ -40,9 +40,9 @@ Contains a map of Page [path](#path) -> [Page object](#page-object).
 
 Think of this instead as `client matchPath`. It is ignored when creating pages during the build. But on the frontend, when resolving the page from the path ([find-path.js]()), it is used (via [reach router](https://github.com/reach/router/blob/master/src/lib/utils.js)) to find the matching page. Note that the [pages are sorted](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/internal-plugins/query-runner/pages-writer.js#L38) so that those with matchPaths are at the end, so that explicit paths are matched first.
 
-This is also used by [gatsby-plugin-create-client-paths](/packages/gatsby-plugin-create-client-paths/?=client). It duplicates pages whose path match some client-only prefix (e.g. `/app/`). The duplicated page has a `matchPath` so that it is resolved first on the frontend.
+This is also used by [gatsby-plugin-create-client-paths](/plugins/gatsby-plugin-create-client-paths/?=client). It duplicates pages whose path match some client-only prefix (e.g. `/app/`). The duplicated page has a `matchPath` so that it is resolved first on the frontend.
 
-It is also used by [gatsby-plugin-netlify](/packages/gatsby-plugin-netlify/?=netlify) when creating `_redirects`.
+It is also used by [gatsby-plugin-netlify](/plugins/gatsby-plugin-netlify/?=netlify) when creating `_redirects`.
 
 #### jsonName
 

docs/docs/glossary.md

@@ -16,7 +16,7 @@ When you're new to Gatsby there can be a lot of words to learn. This glossary ai
 
 ### AST
 
-Abstract Syntax Tree: A tree representation of the source code that is found during a [compilation](#compiler) step between two languages. For example, [gatsby-transformer-remark](/packages/gatsby-transformer-remark/) will create an AST from [Markdown](#markdown) to describe a Markdown document in a tree structure using the [Remark](#remark) parser.
+Abstract Syntax Tree: A tree representation of the source code that is found during a [compilation](#compiler) step between two languages. For example, [gatsby-transformer-remark](/plugins/gatsby-transformer-remark/) will create an AST from [Markdown](#markdown) to describe a Markdown document in a tree structure using the [Remark](#remark) parser.
 
 ### API
 

docs/docs/glossary/decoupled-drupal.md

@@ -20,7 +20,7 @@ A decoupled Drupal architecture offers two key advantages over a tightly coupled
 - **You can use one content management system to serve multiple frontends** — for example, your Gatsby site, your mobile application, and your smart TV application.
 - **You can develop, change, and upgrade the frontend and backend independently of each other.** Upgrading Drupal doesn't require you to modify your site's appearance.
 
-To use Drupal as a content source for Gatsby, add the [`gatsby-source-drupal`](/packages/gatsby-source-drupal/) plugin to your project. As with Gatsby itself, you install the `gatsby-source-drupal` plugin using [npm](/docs/glossary/#npm).
+To use Drupal as a content source for Gatsby, add the [`gatsby-source-drupal`](/plugins/gatsby-source-drupal/) plugin to your project. As with Gatsby itself, you install the `gatsby-source-drupal` plugin using [npm](/docs/glossary/#npm).
 
 ```shell
 npm install gatsby-source-drupal

docs/docs/glossary/headless-wordpress.md

@@ -15,7 +15,7 @@ Most WordPress installations use _themes_, which are a collection of template fi
 
 The WordPress REST API, on the other hand, returns JSON instead of HTML. Using a content API gives you more flexibility around what kind of frontend you use: vanilla JavaScript, a native mobile application, your Gatsby site, or all of the above.
 
-Gatsby [supports WordPress](/docs/how-to/sourcing-data/sourcing-from-wordpress/) as a content source with the [`gatsby-source-wordpress`](/packages/gatsby-source-wordpress/) plugin. As with Gatsby, you can install the `gatsby-source-wordpress` plugin using [npm](/docs/glossary/#npm):
+Gatsby [supports WordPress](/docs/how-to/sourcing-data/sourcing-from-wordpress/) as a content source with the [`gatsby-source-wordpress`](/plugins/gatsby-source-wordpress/) plugin. As with Gatsby, you can install the `gatsby-source-wordpress` plugin using [npm](/docs/glossary/#npm):
 
 ```shell
 npm install gatsby-source-wordpress

docs/docs/glossary/markdown.md

@@ -47,7 +47,7 @@ When converted to HTML, the preceding Markdown will become the markup below.
 </figure>
 ```
 
-You can use Markdown files as a content source for your Gatsby site. To do so, you'll need to install two plugins: [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem) and [`gatsby-transformer-remark`](/packages/gatsby-transformer-remark/). As with Gatsby itself, you can install both using [npm](/docs/glossary/#npm).
+You can use Markdown files as a content source for your Gatsby site. To do so, you'll need to install two plugins: [`gatsby-source-filesystem`](/plugins/gatsby-source-filesystem) and [`gatsby-transformer-remark`](/plugins/gatsby-transformer-remark/). As with Gatsby itself, you can install both using [npm](/docs/glossary/#npm).
 
 ```shell
 npm install gatsby-source-filesystem gatsby-transformer-remark

docs/docs/glossary/mdx.md

@@ -53,13 +53,13 @@ If you're creating a Gatsby site from scratch, the [gatsby-starter-mdx-basic](ht
 gatsby new my-mdx-starter https://github.com/ChristopherBiscardi/gatsby-starter-mdx-basic
 ```
 
-To use MDX with an existing Gatsby site, add the [`gatsby-plugin-mdx`](/packages/gatsby-plugin-mdx/?=gatsby-plugin-mdx) plugin. As with Gatsby itself, you can install it using [npm](/docs/glossary/#npm). You'll also need to install MDX itself, and the React implementation of MDX.
+To use MDX with an existing Gatsby site, add the [`gatsby-plugin-mdx`](/plugins/gatsby-plugin-mdx/?=gatsby-plugin-mdx) plugin. As with Gatsby itself, you can install it using [npm](/docs/glossary/#npm). You'll also need to install MDX itself, and the React implementation of MDX.
 
 ```shell
 npm install gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react
 ```
 
-Then add `gatsby-plugin-mdx` to your plugins list in `gatsby-config.js`, and set the [configuration options](/packages/gatsby-plugin-mdx/?=gatsby-plugin-mdx#configuration) you prefer.
+Then add `gatsby-plugin-mdx` to your plugins list in `gatsby-config.js`, and set the [configuration options](/plugins/gatsby-plugin-mdx/?=gatsby-plugin-mdx#configuration) you prefer.
 
 MDX enhances Markdown's capabilities so that you can use React components anywhere in your Gatsby-powered site.
 

docs/docs/glossary/npm.md

@@ -41,7 +41,7 @@ This will download and install the latest version of Gatsby, then create a new G
 
 ### Using npm to install Gatsby plugins
 
-Gatsby has a robust collection of [plugins](/plugins/) that add functionality or data sourcing to your Gatsby sites. Adding a plugin as a project dependency uses the same process as installing Gatsby itself. Use `npm install <package-name>`. To add the [gatsby-source-filesystem](/packages/gatsby-source-filesystem), plugin, for example, you'd use the following command.
+Gatsby has a robust collection of [plugins](/plugins/) that add functionality or data sourcing to your Gatsby sites. Adding a plugin as a project dependency uses the same process as installing Gatsby itself. Use `npm install <package-name>`. To add the [gatsby-source-filesystem](/plugins/gatsby-source-filesystem), plugin, for example, you'd use the following command.
 
 ```shell
 npm install gatsby-source-filesystem

docs/docs/glossary/wpgraphql.md

@@ -45,7 +45,7 @@ Use [npm](/docs/glossary#npm) to install [gatsby-source-graphql](/docs/third-par
 npm install gatsby-source-graphql
 ```
 
-Then update `gatsby-config.js`. Add the plugin to your Gatsby instance. Specify the URL of the GraphQL endpoint and set other [configuration options](/packages/gatsby-source-graphql/).
+Then update `gatsby-config.js`. Add the plugin to your Gatsby instance. Specify the URL of the GraphQL endpoint and set other [configuration options](/plugins/gatsby-source-graphql/).
 
 ```javascript
 module.exports = {

docs/docs/how-to/adding-common-features/adding-an-rss-feed.md

@@ -10,13 +10,13 @@ Think of it as a syndicated distribution channel for your site's content.
 
 ## Install
 
-To generate an RSS feed, you can use the [`gatsby-plugin-feed`](/packages/gatsby-plugin-feed/) package. To install this package, run the following command:
+To generate an RSS feed, you can use the [`gatsby-plugin-feed`](/plugins/gatsby-plugin-feed/) package. To install this package, run the following command:
 
 ```shell
 npm install gatsby-plugin-feed
 ```
 
-## How to use [gatsby-plugin-feed](/packages/gatsby-plugin-feed/)
+## How to use [gatsby-plugin-feed](/plugins/gatsby-plugin-feed/)
 
 Once installation is complete, you can now add this plugin to your site's config file, like so:
 
@@ -183,7 +183,7 @@ module.exports = {
 
 ## Happy blogging!
 
-With the [Gatsby feed plugin](/packages/gatsby-plugin-feed/), you can share your writing easily with people subscribed through RSS readers like Feedly or RSS Feed Reader. Now that your feed is set up, you won't really have to think about it; publish a new post, and your RSS feed will automatically update with your Gatsby build. Voilà!
+With the [Gatsby feed plugin](/plugins/gatsby-plugin-feed/), you can share your writing easily with people subscribed through RSS readers like Feedly or RSS Feed Reader. Now that your feed is set up, you won't really have to think about it; publish a new post, and your RSS feed will automatically update with your Gatsby build. Voilà!
 
 ## More resources
 

docs/docs/how-to/adding-common-features/adding-analytics.md

@@ -56,24 +56,24 @@ module.exports = {
 
 > Note: Read more about [gatsby-config.js](/docs/reference/config-files/gatsby-config/)
 
-Full documentation for the plugin can be found [here](/packages/gatsby-plugin-google-gtag/).
+Full documentation for the plugin can be found [here](/plugins/gatsby-plugin-google-gtag/).
 
 There are a number of extra configuration options--both with the Gatsby plugin and also in your Google Analytics account--so you can tailor things to meet your website's needs.
 
 Once this is configured you can deploy your site to test! If you navigate to the homepage of Google Analytics, you should see a dashboard with different statistics.
 
 ## Other Gatsby analytics plugins
 
-- [Google Analytics](/packages/gatsby-plugin-google-analytics/)
-- [Google Tag Manager](/packages/gatsby-plugin-google-tagmanager/)
-- [Segment](/packages/gatsby-plugin-segment-js)
-- [Amplitude Analytics](/packages/gatsby-plugin-amplitude-analytics)
-- [Fathom](/packages/gatsby-plugin-fathom/)
-- [Baidu](/packages/gatsby-plugin-baidu-analytics/)
-- [Matomo (formerly Piwik)](/packages/gatsby-plugin-matomo/)
-- [Simple Analytics](/packages/gatsby-plugin-simple-analytics)
-- [Parse.ly Analytics](/packages/gatsby-plugin-parsely-analytics/)
-- [GoatCounter](/packages/gatsby-plugin-goatcounter/)
-- [PostHog](/packages/gatsby-plugin-posthog-analytics/)
-- [Plausible](/packages/gatsby-plugin-plausible/)
-- [Vercel](/packages/gatsby-plugin-vercel/)
+- [Google Analytics](/plugins/gatsby-plugin-google-analytics/)
+- [Google Tag Manager](/plugins/gatsby-plugin-google-tagmanager/)
+- [Segment](/plugins/gatsby-plugin-segment-js)
+- [Amplitude Analytics](/plugins/gatsby-plugin-amplitude-analytics)
+- [Fathom](/plugins/gatsby-plugin-fathom/)
+- [Baidu](/plugins/gatsby-plugin-baidu-analytics/)
+- [Matomo (formerly Piwik)](/plugins/gatsby-plugin-matomo/)
+- [Simple Analytics](/plugins/gatsby-plugin-simple-analytics)
+- [Parse.ly Analytics](/plugins/gatsby-plugin-parsely-analytics/)
+- [GoatCounter](/plugins/gatsby-plugin-goatcounter/)
+- [PostHog](/plugins/gatsby-plugin-posthog-analytics/)
+- [Plausible](/plugins/gatsby-plugin-plausible/)
+- [Vercel](/plugins/gatsby-plugin-vercel/)

docs/docs/how-to/adding-common-features/adding-search.md

@@ -2,66 +2,49 @@
 title: Adding Search
 ---
 
-See below for a list of guides in this section, or keep reading for an overview on adding search functionality to your site.
-
-<GuideList slug={props.slug} />
-
-## Site search overview
-
-Before going through the steps for adding search to your Gatsby website, examine the components needed for adding search to a website.
-
-There are three required components for adding search to your Gatsby website:
-
-1. index
-2. engine
-3. UI
+There are three required components for adding search to your Gatsby website: the **search index**, the **search engine**, and **search UI**.
 
 ## Site search components
 
-### Search index
-
-The search index is a copy of your data stored in a search-friendly format. An index is for optimizing speed and performance when executing a search query. Without an index, every search would need to scan every page in your site—which quickly becomes inefficient.
-
-### Search engine
-
-The search engine takes a search query, runs it through the search index, and returns any matching documents.
-
-### Search UI
-
-The UI component provides an interface to the user, which allows them to write search queries and view the results of each query.
+| Search Component  | Description                                                                                                                                                                                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Search index**  | The search index is a copy of your data stored in a search-friendly format. An index is for optimizing speed and performance when executing a search query. Without an index, every search would need to scan every page in your site—which quickly becomes inefficient. |
+| **Search engine** | The search engine indexes your content, takes a search query, runs it through theindex, and returns any matching documents. Search engines can be hosted services (like Algolia) or open-source that you can self-host (like Elastic)                                    |
+| **Search UI**     | A UI component on your site that allows users to write search queries and view the results of each query. Some search providers provide out of the box React components that you can drop into Gatsby sites.                                                             |  |
 
 ## Adding search to your site
 
-Now that you know the three required components, there are a few ways to approach adding search to your Gatsby-powered site.
-
-### Use an open source search engine
+There are a few ways to approach adding search to your Gatsby-powered site.
 
-Using an open source search engine is always free and allows you to enable offline search for your site. Note that you need to be careful with offline search because the entire search index has to be brought into the client, which can affect the bundle size significantly.
+### Client-side search
 
-Open source libraries like [`elasticlunr`](https://www.npmjs.com/package/elasticlunr), [`flexsearch`](https://github.com/nextapps-de/flexsearch) or [`js-search`](https://github.com/bvaughn/js-search) can be used to enable search for your site.
+It is possible to do all the work in your Gatsby site without needing a third-party solution. This involves writing a bit of code, but using less services. With large amounts of content to index, it can also increase the bundle size significantly.
 
-Doing so will require you to create a search index when your site is built. For [`elasticlunr`](https://www.npmjs.com/package/elasticlunr), there is a plugin called [`gatsby-plugin-elasticlunr-search`](https://github.com/gatsby-contrib/gatsby-plugin-elasticlunr-search) that creates a search index automatically. For [`flexsearch`](https://github.com/nextapps-de/flexsearch) there is a plugin called [`gatsby-plugin-flexsearch`](https://github.com/tmsss/gatsby-plugin-flexsearch).
+One way of doing this is to use the `js-search` library:
 
-For other libraries, you can use a combination of [`onCreateNode`](/docs/reference/config-files/gatsby-node/#onCreateNode), [`setFieldsOnGraphQLNodeType`](/docs/reference/config-files/gatsby-node/#setFieldsOnGraphQLNodeType) and [`sourceNodes`](/docs/reference/config-files/gatsby-node/#sourceNodes) from the Gatsby node API to create the search index and make it available in GraphQL. For more info on how to do this check out [`gatsby-plugin-elasticlunr-search`'s source code](https://github.com/gatsby-contrib/gatsby-plugin-elasticlunr-search/blob/master/src/gatsby-node.js#L96-L131).
+- [Adding Search with JS Search](/docs/adding-search-with-js-search)
 
-Another option is to generate the search index at the end of the build using the [`onPostBuild`](/docs/reference/config-files/gatsby-node/#onPostBuild) node API. This approach is used by [`gatsby-plugin-lunr`](https://github.com/humanseelabs/gatsby-plugin-lunr) to build a multilanguage index.
+There are two Gatsby plugins that support this as well:
 
-After building the search index and including it in Gatsby's data layer, you will need to allow the user to search your website. This is typically done by using a text input to capture the search query, then using one of the libraries mentioned above to retrieve the desired document(s).
+- [gatsby-plugin-elasticlunr-search](/plugins/@gatsby-contrib/gatsby-plugin-elasticlunr-search)
+- [gatsby-plugin-local-search](/plugins/gatsby-plugin-local-search)
 
 ### Use an API-based search engine
 
 Another option is to use an external search engine. This solution is much more scalable as visitors to your site don't have to download your entire search index (which becomes very large as your site grows) in order to search your site. The trade-off is you'll need to pay for hosting the search engine or pay for a commercial search service.
 
-There are many available both open source that you can host yourself and commercial hosted options.
+There are many options available, including both self-hosted and commercially hosted open source:
 
 - [ElasticSearch](https://www.elastic.co/products/elasticsearch) — OSS and has commercial hosting available
 - [Solr](http://lucene.apache.org/solr/) — OSS and has commercial hosting available
 - [Algolia](https://www.algolia.com/) — Commercial
 
-If you're building a documentation website you can use [Algolia's DocSearch feature](https://community.algolia.com/docsearch/). It will automatically create a search index from the content of your pages.
+Of these, the most common solution is Algolia. The Gatsby docs include a guide to adding Algolia to your site:
+
+- [Adding Search with Algolia](/docs/adding-search-with-algolia)
 
-If your website does not qualify as documentation, you need to collect the search index at build time and upload it using [`gatsby-plugin-algolia`](https://github.com/algolia/gatsby-plugin-algolia).
+When using Algolia, they host the search index and search engine for you. Your search queries will be sent to their servers which will respond with any results. For UI components, Algolia provides a [React library](https://github.com/algolia/react-instantsearch) has helpful components.
 
-When using Algolia, they host the search index and search engine for you. Your search queries will be sent to their servers which will respond with any results. You'll need to implement your own UI; Algolia provides a [React library](https://github.com/algolia/react-instantsearch) which may have components you'd like to use.
+If you're building a documentation website you can use [Algolia's DocSearch feature](https://community.algolia.com/docsearch/). It will automatically create a search index from the content of your pages.
 
-Elasticsearch has several React component libraries for search e.g. https://github.com/appbaseio/reactivesearch
+Elasticsearch also has several React component libraries for search, such as [ReactiveSearch](https://github.com/appbaseio/reactivesearch)

docs/docs/how-to/adding-common-features/creating-a-sitemap.md

@@ -8,9 +8,9 @@ An [XML sitemap](https://support.google.com/webmasters/answer/156184?hl=en) list
 
 Think of it as a map for your website. It shows what all of the pages are on your website.
 
-## Using [gatsby-plugin-sitemap](/packages/gatsby-plugin-sitemap/)
+## Using [gatsby-plugin-sitemap](/plugins/gatsby-plugin-sitemap/)
 
-To generate an XML sitemap, you will use the [`gatsby-plugin-sitemap`](/packages/gatsby-plugin-sitemap/) package.
+To generate an XML sitemap, you will use the [`gatsby-plugin-sitemap`](/plugins/gatsby-plugin-sitemap/) package.
 
 Install the package by running the following command:
 `npm install gatsby-plugin-sitemap`
@@ -34,7 +34,7 @@ Next run a build (`npm run build`) since the sitemap generation will only happen
 
 ### Additional modifications
 
-Additional modification steps are available in the [`gatsby-plugin-sitemap` documentation](/packages/gatsby-plugin-sitemap)
+Additional modification steps are available in the [`gatsby-plugin-sitemap` documentation](/plugins/gatsby-plugin-sitemap)
 
 ## More information
 

docs/docs/how-to/adding-common-features/processing-payments-with-stripe.md

@@ -31,7 +31,7 @@ Several tutorials, plugins and starters exist to help you get up and running wit
 
 ### Plugins
 
-- [gatsby-source-stripe](/packages/gatsby-source-stripe/): This plugin allows you to bring your product and SKU data into your Gatsby site at build time to be [used with Stripe Checkout](/tutorial/ecommerce-tutorial/#example-2-import-skus-via-source-plugin).
+- [gatsby-source-stripe](/plugins/gatsby-source-stripe/): This plugin allows you to bring your product and SKU data into your Gatsby site at build time to be [used with Stripe Checkout](/tutorial/ecommerce-tutorial/#example-2-import-skus-via-source-plugin).
 
 ### Starters & Examples
 

docs/docs/how-to/adding-common-features/seo.md

@@ -9,7 +9,7 @@ Gatsby can help your site rank and perform better in search engines. Using Gatsb
 Because Gatsby pages are server-side rendered, all the page content is available to Googlebot and other search engine crawlers.
 You can see this by viewing the source for this page in your browser, Right-Click => View source. You'll see the fully rendered HTML document.
 
-When you've installed [`gatsby-plugin-offline`](/packages/gatsby-plugin-offline/), you'll see a partial HTML document that does not contain the HTML you were hoping for. By using `gatsby-plugin-offline`, we can optimize bandwidth consumption and not let your users download too much data. Serving a partial HTML document is okay. Google and other search engines will still see the full HTML because `gatsby-plugin-offline` only starts working on the second-page load. A search engine always runs a page in Sandbox mode, which essentially is the first visit.
+When you've installed [`gatsby-plugin-offline`](/plugins/gatsby-plugin-offline/), you'll see a partial HTML document that does not contain the HTML you were hoping for. By using `gatsby-plugin-offline`, we can optimize bandwidth consumption and not let your users download too much data. Serving a partial HTML document is okay. Google and other search engines will still see the full HTML because `gatsby-plugin-offline` only starts working on the second-page load. A search engine always runs a page in Sandbox mode, which essentially is the first visit.
 
 As a website owner, how do I test my site is serving its HTML correctly when `gatsby-plugin-offline` is being used? It would be best if you used your terminal of choice to visit your website. You can crawl your site by running the following command:
 

docs/docs/how-to/custom-configuration/add-custom-webpack-config.md

@@ -17,7 +17,7 @@ Gatsby does multiple webpack builds with somewhat different configuration. Gatsb
 
 Check [webpack.config.js](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/webpack.config.js) for the source.
 
-There are many plugins in the Gatsby repo using this API to look to for examples e.g. [Sass](/packages/gatsby-plugin-sass/), [TypeScript](/packages/gatsby-plugin-typescript/), [Glamor](/packages/gatsby-plugin-glamor/), and many more!
+There are many plugins in the Gatsby repo using this API to look to for examples e.g. [Sass](/plugins/gatsby-plugin-sass/), [TypeScript](/plugins/gatsby-plugin-typescript/), [Glamor](/plugins/gatsby-plugin-glamor/), and many more!
 
 ## Examples
 

docs/docs/how-to/custom-configuration/eslint.md

@@ -38,7 +38,7 @@ module.exports = {
 }
 ```
 
-Note: When there is no ESLint file Gatsby implicitly adds a barebones ESLint loader. This loader pipes ESLint feedback into the terminal window where you are running or building Gatsby and also to the console in your browser developer tools. This gives you consolidated, immediate feedback on newly-saved files. When you include a custom `.eslintrc` file, Gatsby gives you full control over the ESLint configuration. This means that it will override the built-in `eslint-loader` and you need to enable any and all rules yourself. One way to do this is to use the Community plugin [`gatsby-plugin-eslint`](/packages/gatsby-plugin-eslint/). This also means that the default [ESLint config Gatsby ships with](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/eslint-config.ts) will be entirely overwritten. If you would still like to take advantage of those rules, you'll need to copy them to your local file.
+Note: When there is no ESLint file Gatsby implicitly adds a barebones ESLint loader. This loader pipes ESLint feedback into the terminal window where you are running or building Gatsby and also to the console in your browser developer tools. This gives you consolidated, immediate feedback on newly-saved files. When you include a custom `.eslintrc` file, Gatsby gives you full control over the ESLint configuration. This means that it will override the built-in `eslint-loader` and you need to enable any and all rules yourself. One way to do this is to use the Community plugin [`gatsby-plugin-eslint`](/plugins/gatsby-plugin-eslint/). This also means that the default [ESLint config Gatsby ships with](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/eslint-config.ts) will be entirely overwritten. If you would still like to take advantage of those rules, you'll need to copy them to your local file.
 
 ### Disabling ESLint
 

docs/docs/how-to/custom-configuration/typescript.md

@@ -26,7 +26,7 @@ The example above uses the power of TypeScript, in combination with exported typ
 
 ## Other resources
 
-TypeScript integration is supported through automatically including [`gatsby-plugin-typescript`](/packages/gatsby-plugin-typescript/). Visit that link to see configuration options and limitations of this setup.
+TypeScript integration is supported through automatically including [`gatsby-plugin-typescript`](/plugins/gatsby-plugin-typescript/). Visit that link to see configuration options and limitations of this setup.
 
 If you are new to TypeScript, check out these other resources to learn more:
 

docs/docs/how-to/images-and-media/importing-assets-into-files.md

@@ -142,4 +142,4 @@ query($slug: String!) {
 }
 ```
 
-Read more about querying for files in [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/).
+Read more about querying for files in [`gatsby-source-filesystem`](/plugins/gatsby-source-filesystem/).

docs/docs/how-to/images-and-media/preprocessing-external-images.md

@@ -4,7 +4,7 @@ title: Preprocessing External Images
 
 Gatsby allows powerful image processing features using the [`Sharp`](https://github.com/lovell/sharp/) library to automatically process images to be performant, with features like lazy-loading. That said, this only works if the image is a `File` node in the GraphQL layer.
 
-If you want the same functionality for files that are remotely hosted online and not located in your Git repo, [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/) has an API called `createRemoteFileNode` to solve this.
+If you want the same functionality for files that are remotely hosted online and not located in your Git repo, [`gatsby-source-filesystem`](/plugins/gatsby-source-filesystem/) has an API called `createRemoteFileNode` to solve this.
 
 This guide will show you how to use the `createRemoteFileNode` process and get the same benefits of gatsby-transformer-sharp with externally sourced images.
 

docs/docs/how-to/images-and-media/using-cloudinary-image-service.md

@@ -4,7 +4,7 @@ title: Using Cloudinary image service for media optimization
 
 Cloudinary is a cloud-based end-to-end media management platform that provides solutions to help site creators serve optimized media files (images and videos) to their audiences. It also provides a lot of optional transformations that can be carried out on these media assets.
 
-In this guide you will take a look at the [gatsby-source-cloudinary](/packages/gatsby-source-cloudinary/) and [gatsby-transformer-cloudinary](/packages/gatsby-transformer-cloudinary/) plugins which you can use to improve the experience of handling images on Gatsby sites.
+In this guide you will take a look at the [gatsby-source-cloudinary](/plugins/gatsby-source-cloudinary/) and [gatsby-transformer-cloudinary](/plugins/gatsby-transformer-cloudinary/) plugins which you can use to improve the experience of handling images on Gatsby sites.
 
 Plugins are generally used to abstract functionality in Gatsby. In this case, the `gatsby-source-cloudinary` plugin is a [source plugin](/docs/how-to/plugins-and-themes/creating-a-source-plugin/) which helps to connect Cloudinary media storage capabilities to your site.
 
@@ -152,5 +152,5 @@ module.exports = {
 
 - [Faster Sites with Optimized Media Assets by William Imoh](/blog/2020-01-12-faster-sites-with-optimized-media-assets/)
 - [Gatsby Transformer Cloudinary](https://www.npmjs.com/package/gatsby-transformer-cloudinary)
-- [Gatsby Source Cloudinary](/packages/gatsby-source-cloudinary/)
+- [Gatsby Source Cloudinary](/plugins/gatsby-source-cloudinary/)
 - [Aspect ratio parameter](https://cloudinary.com/documentation/image_transformation_reference#aspect_ratio_parameter)

docs/docs/how-to/images-and-media/using-gatsby-image.md

@@ -8,7 +8,7 @@ Using images in Gatsby components and pages requires four steps to take advantag
 
 <ImageModel initialLayer="Install" />
 
-`gatsby-image` is a React component designed to work seamlessly with Gatsby’s GraphQL queries ([`gatsby-image` plugin README](/packages/gatsby-image/)). It combines [Gatsby’s native image processing](https://image-processing.gatsbyjs.org/) capabilities with advanced image loading techniques to easily and completely optimize image loading for your sites. `gatsby-image` uses [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/) to power its image transformations.
+`gatsby-image` is a React component designed to work seamlessly with Gatsby’s GraphQL queries ([`gatsby-image` plugin README](/plugins/gatsby-image/)). It combines [Gatsby’s native image processing](https://image-processing.gatsbyjs.org/) capabilities with advanced image loading techniques to easily and completely optimize image loading for your sites. `gatsby-image` uses [gatsby-plugin-sharp](/plugins/gatsby-plugin-sharp/) to power its image transformations.
 
 > _Warning: gatsby-image is **not** a drop-in replacement for `<img />`. It’s optimized for fixed width/height images and images that stretch the full width of a container. Some ways you can use `<img />` won’t work with gatsby-image._
 
@@ -85,7 +85,7 @@ module.exports = {
   lessonTitle="Install gatsby-image and source local images from the filesystem"
 />
 
-4. Write a GraphQL query using one of the included [GraphQL “fragments”](/packages/gatsby-image/#fragments) which specify the fields needed by `gatsby-image` to create a responsive, optimized image. This example queries for an image at a path relative to the location specified in the `gatsby-source-filesystem` options using the `GatsbyImageSharpFluid` fragment.
+4. Write a GraphQL query using one of the included [GraphQL “fragments”](/plugins/gatsby-image/#fragments) which specify the fields needed by `gatsby-image` to create a responsive, optimized image. This example queries for an image at a path relative to the location specified in the `gatsby-source-filesystem` options using the `GatsbyImageSharpFluid` fragment.
 
 ```jsx:title=src/pages/my-dogs.js
 import React from "react"
@@ -169,7 +169,7 @@ So this is all very nice and it’s far better to be able to use this from npm v
 ### Additional resources
 
 - [Gatsby Image API docs](/docs/reference/built-in-components/gatsby-image/)
-- [gatsby-image plugin README file](/packages/gatsby-image/)
+- [gatsby-image plugin README file](/plugins/gatsby-image/)
 - [Source code for an example site using gatsby-image](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-gatsby-image)
 - [Blog articles about gatsby-image](/blog/tags/gatsby-image/)
 - [Starters that use gatsby-image](/starters/?d=gatsby-image&v=2)

docs/docs/how-to/images-and-media/working-with-video.md

@@ -8,7 +8,7 @@ The easiest method for including video on a Gatsby site is to source an uploaded
 
 ## Embedding hosted videos in Markdown
 
-There are numerous Gatsby plugins for working with hosted video in your Markdown posts and pages. We recommend checking out the [gatsby-remark-embed-video](/packages/gatsby-remark-embed-video/?=video) plugin for sourcing from a variety of hosts like YouTube or Vimeo.
+There are numerous Gatsby plugins for working with hosted video in your Markdown posts and pages. We recommend checking out the [gatsby-remark-embed-video](/plugins/gatsby-remark-embed-video/?=video) plugin for sourcing from a variety of hosts like YouTube or Vimeo.
 
 ### Writing custom components for hosted video
 

docs/docs/how-to/local-development/gatsby-on-windows.md

@@ -5,7 +5,7 @@ title: Gatsby on Windows
 ## Setting up your environment for building native Node.js modules
 
 Many Gatsby plugins and themes require building native Node.js modules, e.g.
-[Sharp (a common Gatsby dependency used for image processing)](/packages/gatsby-plugin-sharp/).
+[Sharp (a common Gatsby dependency used for image processing)](/plugins/gatsby-plugin-sharp/).
 To do so, you need a functional build environment (Python and Visual C++ Build
 Tools).
 

docs/docs/how-to/local-development/troubleshooting-common-errors.md

@@ -32,11 +32,11 @@ For some plugins like emotion, styled-components, or Sass, it won't be enough to
 
 Here are some examples of plugins that require you to install more than just the plugin:
 
-- [gatsby-plugin-emotion](/packages/gatsby-plugin-emotion/): `@emotion/react`, and `@emotion/styled`
-- [gatsby-plugin-styled-components](/packages/gatsby-plugin-styled-components/): `styled-components`, and `babel-plugin-styled-components`
-- [gatsby-plugin-sass](/packages/gatsby-plugin-sass/): `node-sass`, or `sass`
-- [gatsby-plugin-material-ui](/packages/gatsby-plugin-material-ui/): `@material-ui/styles`
-- [gatsby-image](/packages/gatsby-image/): `gatsby-transformer-sharp`, and `gatsby-plugin-sharp`
+- [gatsby-plugin-emotion](/plugins/gatsby-plugin-emotion/): `@emotion/react`, and `@emotion/styled`
+- [gatsby-plugin-styled-components](/plugins/gatsby-plugin-styled-components/): `styled-components`, and `babel-plugin-styled-components`
+- [gatsby-plugin-sass](/plugins/gatsby-plugin-sass/): `node-sass`, or `sass`
+- [gatsby-plugin-material-ui](/plugins/gatsby-plugin-material-ui/): `@material-ui/styles`
+- [gatsby-image](/plugins/gatsby-image/): `gatsby-transformer-sharp`, and `gatsby-plugin-sharp`
 
 Rather than packaging up the other dependent libraries alongside these plugins, they can stay smaller in size when they are published and are able to rely on alternative implementations. One example is `gatsby-plugin-sass` that can use either the Node.js or Dart implementations of Sass.
 

docs/docs/how-to/performance/add-a-manifest-file.md

@@ -14,7 +14,7 @@ Quoting [Google](https://developers.google.com/web/fundamentals/web-app-manifest
 
 > The web app manifest is a simple JSON file that tells the browser about your web application and how it should behave when 'installed' on the user's mobile device or desktop.
 
-[Gatsby's manifest plugin](/packages/gatsby-plugin-manifest/) configures Gatsby to create a `manifest.webmanifest` file on every site build.
+[Gatsby's manifest plugin](/plugins/gatsby-plugin-manifest/) configures Gatsby to create a `manifest.webmanifest` file on every site build.
 
 ## Using `gatsby-plugin-manifest`
 
@@ -53,4 +53,4 @@ npm install gatsby-plugin-manifest
 }
 ```
 
-That's all you need to get started with adding a web manifest to a Gatsby site. The example given reflects a base configuration -- check out the [plugin reference](/packages/gatsby-plugin-manifest/?=gatsby-plugin-manifest#automatic-mode) for more options.
+That's all you need to get started with adding a web manifest to a Gatsby site. The example given reflects a base configuration -- check out the [plugin reference](/plugins/gatsby-plugin-manifest/?=gatsby-plugin-manifest#automatic-mode) for more options.

docs/docs/how-to/performance/add-offline-support-with-a-service-worker.md

@@ -5,7 +5,7 @@ title: Adding Offline Support with a Service Worker
 If you've run an [audit with Lighthouse](/docs/how-to/performance/audit-with-lighthouse/), you may have noticed a lackluster score in the "Progressive Web App" category. Let's address how you can improve that score.
 
 1. You can [add a manifest file](/docs/how-to/performance/add-a-manifest-file/). Ensure that the manifest plugin is listed _before_ the offline plugin so that the offline plugin can cache the created `manifest.webmanifest`.
-2. You can also add offline support, since another requirement for a website to qualify as a PWA is the use of a [service worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API). [Gatsby's offline plugin](/packages/gatsby-plugin-offline/) makes a Gatsby site work offline--and makes it more resistant to bad network conditions--by creating a service worker for your site.
+2. You can also add offline support, since another requirement for a website to qualify as a PWA is the use of a [service worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API). [Gatsby's offline plugin](/plugins/gatsby-plugin-offline/) makes a Gatsby site work offline--and makes it more resistant to bad network conditions--by creating a service worker for your site.
 
 ## What is a service worker?
 
@@ -76,7 +76,7 @@ That's all! Gatsby will register your custom service worker.
 
 ## Removing the service worker
 
-If you would like to fully remove the service worker from your site, you can use the plugin `gatsby-plugin-remove-serviceworker` in place of `gatsby-plugin-offline`. See [the README for `gatsby-plugin-offline`](/packages/gatsby-plugin-offline/#remove) for instructions how to do this.
+If you would like to fully remove the service worker from your site, you can use the plugin `gatsby-plugin-remove-serviceworker` in place of `gatsby-plugin-offline`. See [the README for `gatsby-plugin-offline`](/plugins/gatsby-plugin-offline/#remove) for instructions how to do this.
 
 ## References
 

docs/docs/how-to/plugins-and-themes/configuring-usage-with-plugin-options.md

@@ -45,12 +45,12 @@ Any JavaScript data type can be passed in as an option.
 
 The following table lists possible options values and an example plugin that makes use of them.
 
-| Data Type | Sample Value                     | Example Plugin                                                    |
-| --------- | -------------------------------- | ----------------------------------------------------------------- |
-| Boolean   | `true`                           | [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp/)           |
-| String    | `/src/data/`                     | [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/) |
-| Array     | `["/about-us/", "/projects/*"]`  | [`gatsby-plugin-offline`](/packages/gatsby-plugin-offline/)       |
-| Object    | `{ default: "./src/layout.js" }` | [`gatsby-plugin-mdx`](/packages/gatsby-plugin-mdx/)               |
+| Data Type | Sample Value                     | Example Plugin                                                   |
+| --------- | -------------------------------- | ---------------------------------------------------------------- |
+| Boolean   | `true`                           | [`gatsby-plugin-sharp`](/plugins/gatsby-plugin-sharp/)           |
+| String    | `/src/data/`                     | [`gatsby-source-filesystem`](/plugins/gatsby-source-filesystem/) |
+| Array     | `["/about-us/", "/projects/*"]`  | [`gatsby-plugin-offline`](/plugins/gatsby-plugin-offline/)       |
+| Object    | `{ default: "./src/layout.js" }` | [`gatsby-plugin-mdx`](/plugins/gatsby-plugin-mdx/)               |
 
 **Note**: Themes (which are a type of plugin) are able to receive options from a site's `gatsby-config.js` to be used in its `gatsby-config.js` in order to allow themes to be composed together. This is done by exporting the `gatsby-config.js` as a function instead of an object. You can see an example of this in the [`gatsby-theme-blog`](https://github.com/gatsbyjs/themes/tree/master/packages/gatsby-theme-blog) and [`gatsby-theme-blog-core`](https://github.com/gatsbyjs/themes/tree/master/packages/gatsby-theme-blog-core) repositories. Plugins are not capable of this functionality.
 

docs/docs/how-to/plugins-and-themes/converting-a-starter.md

@@ -68,7 +68,7 @@ There may be other locations where you will need to update the path resolution l
 
 ## Sourcing pages
 
-Gatsby by default sources pages relative from `src/pages`, like a regular Gatsby site does. However, if you would like to source pages from a different directory you'll have to setup [`gatsby-plugin-page-creator`](/packages/gatsby-plugin-page-creator/).
+Gatsby by default sources pages relative from `src/pages`, like a regular Gatsby site does. However, if you would like to source pages from a different directory you'll have to setup [`gatsby-plugin-page-creator`](/plugins/gatsby-plugin-page-creator/).
 
 ```shell
 npm install gatsby-plugin-page-creator

docs/docs/how-to/plugins-and-themes/creating-a-generic-plugin.md

@@ -53,7 +53,7 @@ exports.sourceNodes = ({ actions, createNodeId, createContentDigest }) => {
 }
 ```
 
-The above code block creates a node called `"Test Node"` as seen from the `title` parameter. If this process is successful restarting the server will make the `allTestNode` query available at `localhost:8000/___graphql`.
+The above code block creates a node called `"Test Node"` as seen from the `title` parameter. If this process is successful restarting the server will make the `allTestNode` query available at `http://localhost:8000/___graphql`.
 
 > Libraries like [Axios](https://www.npmjs.com/package/axios) can be used to handle calls in the `gatsby-node.js` file
 

docs/docs/how-to/plugins-and-themes/creating-a-source-plugin.md

@@ -17,7 +17,7 @@ Source plugins convert data from any source into a format that Gatsby can proces
 
 There may not be [an existing plugin](/plugins/?=gatsby-source) for your data source, so you can create your own.
 
-_**NOTE:** if your data is local i.e. on your file system and part of your site's repo, then you generally don't want to create a new source plugin. Instead you want to use [gatsby-source-filesystem](/packages/gatsby-source-filesystem/) which handles reading and watching files for you. You can then use [transformer plugins](/plugins/?=gatsby-transformer) like [gatsby-transformer-yaml](/packages/gatsby-transformer-yaml/) to make queryable data from files._
+_**NOTE:** if your data is local i.e. on your file system and part of your site's repo, then you generally don't want to create a new source plugin. Instead you want to use [gatsby-source-filesystem](/plugins/gatsby-source-filesystem/) which handles reading and watching files for you. You can then use [transformer plugins](/plugins/?=gatsby-transformer) like [gatsby-transformer-yaml](/plugins/gatsby-transformer-yaml/) to make queryable data from files._
 
 ## How to create a source plugin
 
@@ -269,7 +269,7 @@ exports.sourceNodes = async ({
 // ...
 ```
 
-You can read about each of the packages that are working together in [Apollo's docs](https://www.apollographql.com/docs/react/). The end result is creating a `client` that you can use to call methods like `query` to get data from the source it's configured to work with. In this case, that is `localhost:4000` where you should have the API running. If you can't configure the API to run locally, you can update the URLs for the client to use `gatsby-source-plugin-api.glitch.me` where a version of the API is deployed, instead of `localhost:4000`.
+You can read about each of the packages that are working together in [Apollo's docs](https://www.apollographql.com/docs/react/). The end result is creating a `client` that you can use to call methods like `query` to get data from the source it's configured to work with. In this case, that is `http://localhost:4000` where you should have the API running. If you can't configure the API to run locally, you can update the URLs for the client to use `gatsby-source-plugin-api.glitch.me` where a version of the API is deployed, instead of `http://localhost:4000`.
 
 #### Query data from the API
 
@@ -924,8 +924,8 @@ You can test that this is working by running the site again and updating one of
 
 Follow these steps to test it out:
 
-1. Open up your site at `localhost:8000` after you run `gatsby develop`
-2. Open up the GraphQL playground at `localhost:4000` (if you are running the `api` folder locally) or `https://gatsby-source-plugin-api.glitch.me/` and first run a query for posts:
+1. Open up your site at `http://localhost:8000` after you run `gatsby develop`
+2. Open up the GraphQL playground at `http://localhost:4000` (if you are running the `api` folder locally) or `https://gatsby-source-plugin-api.glitch.me/` and first run a query for posts:
 
 ```graphql
 query {

docs/docs/how-to/plugins-and-themes/using-a-gatsby-theme.md

@@ -2,7 +2,7 @@
 title: How to Use a Theme in an Existing Site
 ---
 
-While you can [get started quickly with a Gatsby theme starter](/docs/how-to/new-site-with-theme/), you can also install a Gatsby theme directly to an existing Gatsby site. Gatsby themes are plugins, so you can [install and use them like any other Gatsby plugin](/docs/how-to/plugins-and-themes/using-a-plugin-in-your-site/).
+While you can [get started quickly with a Gatsby theme starter](/docs/how-to/plugins-and-themes/new-site-with-theme/), you can also install a Gatsby theme directly to an existing Gatsby site. Gatsby themes are plugins, so you can [install and use them like any other Gatsby plugin](/docs/how-to/plugins-and-themes/using-a-plugin-in-your-site/).
 
 ## Installing a Theme
 
@@ -20,7 +20,7 @@ npm install gatsby-theme-blog
 
 Depending on the theme, there may be theme options that can be configured via `gatsby-config.js`.
 
-For example, `gatsby-theme-blog` can take a number of different options. All of them are documented in the [theme's README](/packages/gatsby-theme-blog/) file.
+For example, `gatsby-theme-blog` can take a number of different options. All of them are documented in the [theme's README](/plugins/gatsby-theme-blog/) file.
 
 ```javascript:title=gatsby-config.js
 module.exports = {

docs/docs/how-to/previews-deploys-hosting/deploying-to-netlify.md

@@ -71,5 +71,5 @@ From the site `Overview`, you can go to `Domain Settings`. By adding a custom do
 
 - [A Step-by-Step Guide: Gatsby on Netlify](https://www.netlify.com/blog/2016/02/24/a-step-by-step-guide-gatsby-on-netlify/)
 - More [blog posts on Gatsby + Netlify](/blog/tags/netlify)
-- [Gatsby Netlify CMS](/packages/gatsby-plugin-netlify-cms)
+- [Gatsby Netlify CMS](/plugins/gatsby-plugin-netlify-cms)
 - [Gatsby + Netlify CMS Starter](https://github.com/netlify-templates/gatsby-starter-netlify-cms)