fix(docs): improve Gatsby Image docs

docs/docs/images-and-files.md

@@ -1,8 +1,8 @@
 ---
-title: Images, Video, and Files
+title: Images, Files, and Video
 overview: true
 ---
 
-Gatsby provides multiple solutions for adding images, video, and files into your projects. This section will walk you through several common patterns for handling media in Gatsby projects.
+Gatsby provides multiple solutions for adding images, video, and files into your projects. This section will walk you through several common patterns for handling media with Gatsby.
 
 [[guidelist]]

docs/docs/importing-assets-into-files.md

@@ -2,7 +2,7 @@
 title: "Importing Assets Directly Into Files"
 ---
 
-There are two major ways to import assets, such as images, fonts, and files, into a Gatsby site. The default path is import the file directly. The alternative path, which makes sense for some edge cases, is to use the [static folder](/docs/static-folder).
+There are two major ways to import assets, such as images, fonts, and files, into a Gatsby site. The default path is to import the file directly into a Gatsby template, page, or component. The alternative path, which makes sense for some edge cases, is to use the [static folder](/docs/static-folder).
 
 ## Importing assets with Webpack
 
@@ -29,7 +29,7 @@ export default Header
 
 This ensures that when the project is built, Webpack will correctly move the images into the public folder, and provide us with correct paths.
 
-You can reference files imported with Webpack in CSS, too:
+You can reference files in CSS to import them, too:
 
 ```css
 .Logo {
@@ -43,11 +43,9 @@ If you're using SCSS the imports are relative to the entry SCSS file.
 
 Please be advised that this is also a custom feature of Webpack.
 
-Two alternative ways of handling static assets are described in the next sections.
-
 ## Querying for a `File` in GraphQL using gatsby-source-filesystem
 
-You can query the `publicURL` field of `File` nodes found in your data layer to trigger copying those files to the public directory and get URLs to them.
+You can also import files using GraphQL by querying for them in your data layer, which will trigger copying of those files to the public directory. Querying for the `publicURL` field of `File` nodes will provide URLs you can use in your JavaScript components, pages and templates.
 
 ### Examples:
 
@@ -65,7 +63,48 @@ You can query the `publicURL` field of `File` nodes found in your data layer to
 }
 ```
 
-2. Link to attachments in your Markdown files:
+Reference those PDF files in a page with useStaticQuery:
+
+```jsx
+import React from "react"
+import { useStaticQuery, graphql } from "gatsby"
+
+import Layout from "../components/layout"
+
+const DownloadsPage = () => {
+  const data = useStaticQuery(graphql`
+    {
+      allFile(filter: { extension: { eq: "pdf" } }) {
+        edges {
+          node {
+            publicURL
+            name
+          }
+        }
+      }
+    }
+  `)
+  return (
+    <Layout>
+      <h1>All PDF Downloads</h1>
+      <ul>
+        {data.allFile.edges.map((file, index) => {
+          return (
+            <li key={`pdf-${index}`}>
+              <a href={file.node.publicURL} download>
+                {file.node.name}
+              </a>
+            </li>
+          )
+        })}
+      </ul>
+    </Layout>
+  )
+}
+export default DownloadsPage
+```
+
+2. Link to attachments in the frontmatter of your Markdown files:
 
 ```markdown
 ---
@@ -78,7 +117,7 @@ attachments:
 Hi, this is a great article.
 ```
 
-In the article template component file, you can then query for the attachments:
+In an article template component file, you can then query for the attachments:
 
 ```graphql
 query($slug: String!) {

docs/docs/static-folder.md

@@ -17,25 +17,14 @@ You can create a folder named `static` at the root of your project. Every file y
 
 ### Referencing your static asset
 
-In order to reference assets from the `static` folder in your code, you'll need to [import the `withPrefix` helper function from `gatsby`](/docs/gatsby-link/#prefixed-paths-helper):
+You can reference assets from the `static` folder in your code without anything special required:
 
 ```js
-import { withPrefix } from 'gatsby'
-
 render() {
   // Note: this is an escape hatch and should be used sparingly!
   // Normally we recommend using `import` for getting asset URLs
   // as described in the “Adding Images, Fonts, and Files” page.
-  return <img src={withPrefix('/img/logo.png')} alt="Logo" />;
-}
-```
-
-And make sure you [set `pathPrefix` in your gatsby-config.js](/docs/path-prefix/):
-
-```javascript:title=gatsby-config.js
-module.exports = {
-  // Note: it must *not* have a trailing slash.
-  pathPrefix: `/img`,
+  return <img src={'logo.png'} alt="Logo" />;
 }
 ```
 

docs/docs/using-gatsby-image.md

@@ -2,7 +2,7 @@
 
 `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.
 
-_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._
+> _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._
 
 [Demo](https://using-gatsby-image.gatsbyjs.org/)
 
@@ -33,9 +33,9 @@ This isn’t ideal. Optimized images should be easy and the default.
 
 ## Solution
 
-With Gatsby, we can make images way way better.
+With Gatsby, we can make the experience of working with images way, way better.
 
-`gatsby-image` is designed to work seamlessly with Gatsby’s native image processing capabilities powered by GraphQL and Sharp. To produce perfect images, you only need to:
+`gatsby-image` is designed to work seamlessly with Gatsby’s native image processing capabilities powered by GraphQL and Sharp. To produce perfect images with minimal effort, you can:
 
 1. Install `gatsby-image` and other, necessary dependencies like `gatsby-plugin-sharp` and `gatsby-transformer-sharp`
 
@@ -51,7 +51,7 @@ module.exports = {
 }
 ```
 
-3. Configure `gatsby-source-filesystem` to load images from a folder. In order to use GraphQL to query the image files, the files need to be in a location that is known to Gatsby. This requires an update to `gatsby-config.js` to configure the plugin. Feel free to replace the `path` option with wherever your images are located relative to your project.
+3. Configure `gatsby-source-filesystem` to load images from a folder. In order to use GraphQL to query the image files, the files need to be in a location that is known to Gatsby. This requires an update to `gatsby-config.js` to configure the plugin. Feel free to replace the `path` option to reference wherever your images are located in your project.
 
 ```js:title=gatsby-config.js
 module.exports = {
@@ -70,7 +70,7 @@ module.exports = {
 }
 ```
 
-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 will use `GatsbyImageSharpFluid`. An example of a GraphQL query is below where the path listed is the path relative to the location specified in the `gatsby-source-filesystem` options.
+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.
 
 ```graphql
 file(relativePath: { eq: "images/default.jpg" }) {
@@ -83,7 +83,7 @@ file(relativePath: { eq: "images/default.jpg" }) {
 }
 ```
 
-5. Import `Img` to display the fragment in JSX. There are additional features available with the `Img` tag as well.
+5. Import `Img` to display the fragment in JSX. There are additional features available with the `Img` tag as well, such as the `alt` attribute for accessibility.
 
 ```jsx
 import Img from "gatsby-image"

docs/docs/working-with-images.md

@@ -50,7 +50,7 @@ export const query = graphql`
 Here is an image component that uses the query from the previous example:
 
 ```jsx
-<Img fluid={data.fileName.childImageSharp.fluid} />
+<Img fluid={data.fileName.childImageSharp.fluid} alt="" />
 ```
 
 ## Using Fragments To Standardize Formatting

www/src/data/sidebars/doc-links.yaml

@@ -69,17 +69,17 @@
               link: /docs/eslint/
             - title: Proxying API Requests
               link: /docs/api-proxy/
-        - title: Images, Video, and Files
+        - title: Images, Files, and Video
           link: /docs/images-and-files/
           items:
-            - title: Importing Assets Into Files
+            - title: Importing Assets Directly Into Files
               link: /docs/importing-assets-into-files/
             - title: Using the Static Folder
               link: /docs/static-folder/
-            - title: Working with Images in Gatsby
-              link: /docs/working-with-images/
             - title: Using gatsby-image
               link: /docs/using-gatsby-image/
+            - title: Working with Images in Gatsby
+              link: /docs/working-with-images/
             - title: Preoptimizing your Images
               link: /docs/preoptimizing-images/
             - title: Working With Video