some docs quick wins (#29859)

docs/docs/conceptual/gatsby-core-philosophy.md

@@ -21,7 +21,7 @@ Today's building blocks for the web are components of HTML, CSS, and JavaScript.
 
 We believe that in 5 or 10 years, we'll look back at many of these blocks like we look back at machine code or assembly language today; low-level languages that are great compile targets for higher-level languages that are easier to write in.
 
-Using abstractions like React components, `gatsby-image`, and `gatsby-link`, we've begun to craft this higher-level language. But we're just getting started. Gatsby is a playground for discovering new building blocks for the web.
+Using abstractions like React components, `gatsby-plugin-image`, and `gatsby-link`, we've begun to craft this higher-level language. But we're just getting started. Gatsby is a playground for discovering new building blocks for the web.
 
 To [quote Alan Kay](https://www.youtube.com/watch?v=NdSD07U5uBs):
 
@@ -97,7 +97,7 @@ If you were designing a user interface, you might move advanced or rarely-used f
 
 Progressive disclosure simplifies the experience for most people without limiting the abilities of more advanced users.
 
-We progressively disclose complexity by making features such as modifying webpack / Babel config, `gatsby-image`, and `gatsby-link` opt-in, simple one-off configuration choices. We avoid all-or-nothing "ejection" scenarios where to add further customization you have to leave the tool behind and manage all complexity (e.g. dependencies) yourself.
+We progressively disclose complexity by making features such as modifying webpack / Babel config, `gatsby-plugin-image`, and `gatsby-link` opt-in, simple one-off configuration choices. We avoid all-or-nothing "ejection" scenarios where to add further customization you have to leave the tool behind and manage all complexity (e.g. dependencies) yourself.
 
 [Read more here](https://lengstorf.com/progressive-disclosure-of-complexity/).
 

docs/docs/images-and-files.md

@@ -2,7 +2,7 @@
 title: Images, Files & Video in Gatsby
 ---
 
-Gatsby provides multiple solutions for adding images, video, and files to your projects. And a pro tip: you don't necessarily have to use GraphQL! From [imports](/docs/how-to/images-and-media/importing-assets-into-files/) and use of the [static folder](/docs/how-to/images-and-media/static-folder/) to dynamic queries with [Gatsby Image](/docs/how-to/images-and-media/using-gatsby-image/) to prevent image bloat, you've got options.
+Gatsby provides multiple solutions for adding images, video, and files to your projects. And a pro tip: you don't necessarily have to use GraphQL! From [imports](/docs/how-to/images-and-media/importing-assets-into-files/) and use of the [static folder](/docs/how-to/images-and-media/static-folder/) to dynamic queries with [gatsby-plugin-image](/docs/how-to/images-and-media/using-gatsby-plugin-image/) to prevent image bloat, you've got options.
 
 This section will walk you through several common patterns for handling media with Gatsby, where you can learn about the pros and cons of each method.
 

docs/docs/plugins.md

@@ -4,7 +4,7 @@ title: Plugins
 
 Gatsby plugins are Node.js packages that implement Gatsby APIs. For larger, more complex sites, plugins let you modularize your site customizations into site-specific plugins.
 
-There are many types of Gatsby plugins, including [data sourcing](/plugins/?=gatsby-source), [SEO](/plugins/?=seo), [responsive images](/plugins/gatsby-image/?=gatsby-image), [offline support](/plugins/gatsby-plugin-offline/), [Sass support](/plugins/gatsby-plugin-sass/), [sitemaps](/plugins/gatsby-plugin-sitemap/), [RSS feeds](/plugins/gatsby-plugin-feed/), [TypeScript](/plugins/gatsby-plugin-typescript/), [Google Analytics](/plugins/gatsby-plugin-google-analytics/), and more. You can also [make your own plugins](/docs/creating-plugins/)!
+There are many types of Gatsby plugins, including [data sourcing](/plugins/?=gatsby-source), [SEO](/plugins/?=seo), [responsive images](/plugins/gatsby-plugin-image/?=gatsby-plugin-image), [offline support](/plugins/gatsby-plugin-offline/), [Sass support](/plugins/gatsby-plugin-sass/), [sitemaps](/plugins/gatsby-plugin-sitemap/), [RSS feeds](/plugins/gatsby-plugin-feed/), [TypeScript](/plugins/gatsby-plugin-typescript/), [Google Analytics](/plugins/gatsby-plugin-google-analytics/), and more. You can also [make your own plugins](/docs/creating-plugins/)!
 
 Gatsby themes are a type of plugin that include a `gatsby-config.js` file and add **pre-configured** functionality, data sourcing, and/or UI code to Gatsby sites. To learn more about theme use cases and APIs, check out the [themes section of the docs](/docs/themes/). To learn about how plugins differ from themes and starters refer to the [Plugins, Themes, & Starters conceptual guide](/docs/conceptual/plugins-themes-and-starters/).
 

docs/docs/porting-an-html-site-to-gatsby.md

@@ -560,7 +560,7 @@ website-domain
 
 ## Next steps
 
-Gatsby can handle images through direct imports to page and component files too! The [asset import documentation](/docs/how-to/images-and-media/importing-assets-into-files/) covers this. There is also the [Gatsby Image](/docs/reference/built-in-components/gatsby-image/) component for even deeper optimizations. Once assets are handled through Gatsby, plugins can be used to optimize their processing and delivery.
+Gatsby can handle images through direct imports to page and component files too! The [asset import documentation](/docs/how-to/images-and-media/importing-assets-into-files/) covers this. There is also [gatsby-plugin-image](/docs/how-to/images-and-media/using-gatsby-plugin-image) component for even deeper optimizations. Once assets are handled through Gatsby, plugins can be used to optimize their processing and delivery.
 
 The [building with components doc](/docs/conceptual/building-with-components/) has information about why Gatsby uses React component architecture and how it fits into a Gatsby application.
 

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

@@ -19,7 +19,7 @@ _Both_ Create React App and Gatsby use React and allow users to build apps more
 Gatsby enables some useful performance optimizations for you, by default. Route-based code splitting and pre-loading of the _next_ resources make your application lightning fast, without any additional effort! Further still, the following optimizations and techniques are also available to you:
 
 - `gatsby-link` uses an [intersection observer to preload linked pages](/blog/2019-04-02-behind-the-scenes-what-makes-gatsby-great/#intersectionobserver) when they appear in the viewport, making them feel like they load _instantly_
-- `gatsby-image` will create optimized versions of your images in different sizes, loading a smaller, optimized version of an image and replacing it with a higher resolution version when loading has finished. It also uses an intersection observer to cheaply lazy load images. Check out [the demo](https://using-gatsby-image.gatsbyjs.org/) to see for yourself
+- `gatsby-plugin-image` will create optimized versions of your images in different sizes, loading a smaller, optimized version of an image and replacing it with a higher resolution version when loading has finished. It also uses an intersection observer to cheaply lazy load images. Check out [the demo](https://using-gatsby-image.gatsbyjs.org/) to see for yourself
 
 These features and more work together to make your Gatsby site fast by default. If you'd like a deep dive on these and other performance optimizations, check out [this blog post](/blog/2019-04-02-behind-the-scenes-what-makes-gatsby-great/)
 

docs/docs/reference/built-in-components/gatsby-image.md

@@ -2,6 +2,8 @@
 title: Gatsby Image API
 ---
 
+_This document talks about the deprecated image plugin. Please check out how to work with the new [gatsby-plugin-image](/docs/how-to/images-and-media/using-gatsby-plugin-image)_
+
 Part of what makes Gatsby sites so fast is its recommended approach to handling images. `gatsby-image` is a React component designed to work seamlessly with Gatsby’s [native image processing](https://image-processing.gatsbyjs.org/) capabilities powered by GraphQL and [gatsby-plugin-sharp](/plugins/gatsby-plugin-sharp/) to easily and completely optimize image loading for your sites.
 
 > _Note: gatsby-image is **not** a drop-in replacement for `<img />`. It’s optimized for responsive fixed width/height images and images that stretch the full-width of a container. There are also other ways to [work with images](/docs/images-and-files/) in Gatsby that don't require GraphQL._

docs/docs/working-with-images.md

@@ -2,6 +2,8 @@
 title: Working with Images in Gatsby
 ---
 
+_This document uses the deprecated image plugin. Please check out how to work with the new [gatsby-plugin-image](/docs/how-to/images-and-media/using-gatsby-plugin-image)._
+
 Optimizing images is a challenge on any website. To utilize best practices for performance across devices, you need multiple sizes and resolutions of each image. Luckily, Gatsby has several useful [plugins](/docs/plugins/) that work together to do that for images on [page components](/docs/conceptual/building-with-components/#page-components).
 
 The recommended approach is to use [GraphQL queries](/docs/conceptual/graphql-concepts/) to get images of the optimal size or resolution, then, display them with the [`gatsby-image`](/plugins/gatsby-image/) component.