From e592d8300e14252d63ffff5e237096dd3e8168fb Mon Sep 17 00:00:00 2001
From: Marcy Sutton <marcy.sutton@deque.com>
Date: Fri, 5 Apr 2019 15:30:23 -0700
Subject: [PATCH 1/8] revisit import/static folder docs

---
 docs/docs/adding-images-fonts-files.md   | 165 -----------------------
 docs/docs/gatsby-project-structure.md    |   2 +-
 docs/docs/importing-assets-into-files.md |  97 +++++++++++++
 docs/docs/importing-media-content.md     |   4 +-
 docs/docs/static-folder.md               |  43 +++---
 www/src/data/sidebars/doc-links.yaml     |  16 +--
 6 files changed, 123 insertions(+), 204 deletions(-)
 delete mode 100644 docs/docs/adding-images-fonts-files.md
 create mode 100644 docs/docs/importing-assets-into-files.md

diff --git a/docs/docs/adding-images-fonts-files.md b/docs/docs/adding-images-fonts-files.md
deleted file mode 100644
index 65f2ba512ec3e..0000000000000
--- a/docs/docs/adding-images-fonts-files.md
+++ /dev/null
@@ -1,165 +0,0 @@
----
-title: "Adding Images, Fonts, and Files"
----
-
-With Webpack you can **`import` a file right in a JavaScript module**. This
-tells Webpack to include that file in the bundle. Unlike CSS imports, importing
-a file gives you a string value. This value is the final path you can reference
-in your code, e.g. as the `src` attribute of an image or the `href` of a link to
-a PDF.
-
-To reduce the number of requests to the server, importing images that are less
-than 10,000 bytes returns a
-[data URI](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs)
-instead of a path. This applies to the following file extensions: svg, jpg,
-jpeg, png, gif, mp4, webm, wav, mp3, m4a, aac, and oga.
-
-Here is an example:
-
-```js
-import React from "react"
-import logo from "./logo.png" // Tell Webpack this JS file uses this image
-
-console.log(logo) // /logo.84287d09.png
-
-function Header() {
-  // Import result is the URL of your image
-  return <img src={logo} alt="Logo" />
-}
-
-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.
-
-This works in CSS too:
-
-```css
-.Logo {
-  background-image: url(./logo.png);
-}
-```
-
-Webpack finds all relative module references in CSS (they start with `./`) and
-replaces them with the final paths from the compiled bundle. If you make a typo
-or accidentally delete an important file, you will see a compilation error, just
-like when you import a non-existent JavaScript module. The final filenames in
-the compiled bundle are generated by Webpack from content hashes. If the file
-content changes in the future, Webpack will give it a different name in
-production so you don’t need to worry about long-term caching of assets.
-
-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.
-
-## Query for `File` in GraphQL queries 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.
-
-Examples:
-
-- Copy all `.pdf` files you have in your data layer to your build directory and return URLs to them:
-
-```graphql
-{
-  allFile(filter: { extension: { eq: "pdf" } }) {
-    edges {
-      node {
-        publicURL
-      }
-    }
-  }
-}
-```
-
-- Copy post attachments defined in your Markdown files:
-
-  Link to your attachments in the markdown front matter:
-
-```markdown
----
-title: "Title of article"
-attachments:
-  - "./assets.zip"
-  - "./presentation.pdf"
----
-
-Hi, this is a great article.
-```
-
-In the article template component file, you can query for the attachments:
-
-```graphql
-query($slug: String!) {
-  markdownRemark(fields: { slug: { eq: $slug } }) {
-    html
-    frontmatter {
-      title
-      attachments {
-        publicURL
-      }
-    }
-  }
-}
-```
-
-## Using the `static` Folder
-
-You can also add other assets to a `static` folder at the root of your project. Check the [static folder](/docs/static-folder/) page to learn more.
-
-Note that we normally encourage you to `import` assets in JavaScript files
-instead. This mechanism provides a number of benefits:
-
-- Scripts and stylesheets get minified and bundled together to avoid extra
-  network requests.
-- Missing files cause compilation errors instead of 404 errors for your users.
-- Result filenames include content hashes so you don’t need to worry about
-  browsers caching their old versions.
-
-However, there is an **escape hatch** that you can use to add an asset outside of
-the module system.
-
-If you put a file into the `static` folder, it will **not** be processed by
-Webpack. Instead, it will be copied into the public folder untouched. E.g. if you
-add a file named `sun.jpg` to the static folder, it'll be copied to
-`public/sun.jpg`. To reference assets in the `static` folder, you'll need to
-[import a helper function from `gatsby` named `withPrefix`](/docs/gatsby-link/#add-the-path-prefix-to-paths-using-withprefix).
-You will need to make sure
-[you set `pathPrefix` in your gatsby-config.js for this to work](/docs/path-prefix/).
-
-```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 “Adding Images and Fonts” above this section.
-  return <img src={withPrefix('/img/logo.png')} alt="Logo" />;
-}
-```
-
-Keep in mind the downsides of this approach:
-
-- None of the files in `static` folder get post-processed or minified.
-- Missing files will not be called at compilation time, and will cause 404
-  errors for your users.
-- Result filenames won’t include content hashes so you’ll need to add query
-  arguments or rename them every time they change.
-
-### When to Use the `static` Folder
-
-Normally we recommend importing stylesheets,
-[images, and fonts](#adding-images-fonts-files) from JavaScript. The `static`
-folder is useful as a workaround for a number of less common cases:
-
-- You need a file with a specific name in the build output, such as
-  [`manifest.webmanifest`](https://developer.mozilla.org/en-US/docs/Web/Manifest).
-- You have thousands of images and need to dynamically reference their paths.
-- You want to include a small script like
-  [`pace.js`](http://github.hubspot.com/pace/docs/welcome/) outside of the
-  bundled code.
-- You are using a library that is incompatible with Webpack and need to
-  include it as a `<script>` tag.
diff --git a/docs/docs/gatsby-project-structure.md b/docs/docs/gatsby-project-structure.md
index edd1ddb84bbd9..137874431a1a3 100644
--- a/docs/docs/gatsby-project-structure.md
+++ b/docs/docs/gatsby-project-structure.md
@@ -34,7 +34,7 @@ Inside a Gatsby project, you may see some or all of the following folders and fi
   - **`/templates`** Contains templates for programmatically creating pages. Check out the [templates docs](/docs/building-with-components/#page-template-components) for more detail.
   - **`html.js`** For custom configuration of default .cache/default_html.js. Check out the [custom html docs](/docs/custom-html/) for more detail.
 
-- **`/static`** If you put a file into the static folder, it will not be processed by Webpack. Instead it will be copied into the public folder untouched. Check out the [assets docs](/docs/adding-images-fonts-files/#adding-assets-outside-of-the-module-system) for more detail.
+- **`/static`** If you put a file into the static folder, it will not be processed by Webpack. Instead it will be copied into the public folder untouched. Check out the [assets docs](/docs/static-folder/#adding-assets-outside-of-the-module-system) for more detail.
 
 ### Files
 
diff --git a/docs/docs/importing-assets-into-files.md b/docs/docs/importing-assets-into-files.md
new file mode 100644
index 0000000000000..ba9e1be347f42
--- /dev/null
+++ b/docs/docs/importing-assets-into-files.md
@@ -0,0 +1,97 @@
+---
+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).
+
+## Importing assets with Webpack
+
+With Webpack you can **`import` a file right in a JavaScript module**. This tells Webpack to include that file in the bundle. Unlike CSS imports, importing a file gives you a string value. This value is the final path you can reference in your code, e.g. as the `src` attribute of an image or the `href` of a link to a PDF.
+
+To reduce the number of requests to the server, importing images that are less than 10,000 bytes returns a
+[data URI](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) instead of a path. This applies to the following file extensions: svg, jpg, jpeg, png, gif, mp4, webm, wav, mp3, m4a, aac, and oga.
+
+Here's an example:
+
+```js
+import React from "react"
+import logo from "./logo.png" // Tell Webpack this JS file uses this image
+
+console.log(logo) // /logo.84287d09.png
+
+function Header() {
+  // Import result is the URL of your image
+  return <img src={logo} alt="Logo" />
+}
+
+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:
+
+```css
+.Logo {
+  background-image: url(./logo.png);
+}
+```
+
+Webpack finds all relative module references in CSS (they start with `./`) and replaces them with the final paths from the compiled bundle. If you make a typo or accidentally delete an important file, you will see a compilation error, just like when you import a non-existent JavaScript module. The final filenames in the compiled bundle are generated by Webpack from content hashes. If the file content changes in the future, Webpack will give it a different name in production so you don’t need to worry about long-term caching of assets.
+
+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.
+
+Examples:
+
+- Copy all `.pdf` files you have in your data layer to your build directory and return URLs to them:
+
+```graphql
+{
+  allFile(filter: { extension: { eq: "pdf" } }) {
+    edges {
+      node {
+        publicURL
+      }
+    }
+  }
+}
+```
+
+- Copy post attachments defined in your Markdown files:
+
+  Link to your attachments in the markdown front matter:
+
+```markdown
+---
+title: "Title of article"
+attachments:
+  - "./assets.zip"
+  - "./presentation.pdf"
+---
+
+Hi, this is a great article.
+```
+
+In the article template component file, you can query for the attachments:
+
+```graphql
+query($slug: String!) {
+  markdownRemark(fields: { slug: { eq: $slug } }) {
+    html
+    frontmatter {
+      title
+      attachments {
+        publicURL
+      }
+    }
+  }
+}
+```
diff --git a/docs/docs/importing-media-content.md b/docs/docs/importing-media-content.md
index 81a8c3f23ff73..ca2bb9a4fb31a 100644
--- a/docs/docs/importing-media-content.md
+++ b/docs/docs/importing-media-content.md
@@ -6,8 +6,8 @@ title: Importing Media Content
 
 ## Images, SVG, and PDFs
 
-- [Image graphics can be imported](/docs/adding-images-fonts-files/) with Webpack and queried with GraphQL.
-- Images can also be [included from the `static folder`](/docs/adding-images-fonts-files/#using-the-static-folder).
+- [Image graphics can be imported](/docs/importing-assets-into-files/) with Webpack and queried with GraphQL.
+- Images can also be [included from the `static folder`](/docs/static-folder/).
 - SVG content can be embedded into JSX. Here's a [handy JSX converter](https://transform.now.sh/html-to-jsx/).
 - SVG can be included in `img` tags or CSS backgrounds. [SVG Tips from CSS Tricks](https://css-tricks.com/using-svg/).
 - For PDF files, we recommend embedding an [image of the PDF](https://helpx.adobe.com/acrobat/using/exporting-pdfs-file-formats.html) with [alternative text](https://a11y-101.com/development/infographics), and providing a link to download a [tagged PDF](https://helpx.adobe.com/acrobat/using/creating-accessible-pdfs.html).
diff --git a/docs/docs/static-folder.md b/docs/docs/static-folder.md
index d15e63ca389c8..f8b1babe761fd 100644
--- a/docs/docs/static-folder.md
+++ b/docs/docs/static-folder.md
@@ -1,31 +1,23 @@
 ---
-title: Static folder
+title: Using the Static folder
 ---
 
 In general, every website needs assets: images, stylesheets, scripts, etc. When using Gatsby, we recommend
-[Adding Images, Fonts, and Files](/docs/adding-images-fonts-files/) in JavaScript files,
-because of the benefits it provides:
+[Importing Assets Directly](/docs/importing-assets-into-files/) in JavaScript files, because of the benefits it provides:
 
-- Scripts and stylesheets are minified and bundled together to avoid extra
-  network requests.
+- Scripts and stylesheets are minified and bundled together to avoid extra network requests.
 - Missing files cause compilation errors instead of 404 errors for your users.
-- Result filenames include content hashes so you don’t need to worry about
-  browsers caching their old versions.
+- Result filenames include content hashes so you don’t need to worry about browsers caching their old versions.
 
-However, there is an **escape hatch** that you can use to add an asset outside of
-the module system.
+However, there is an **escape hatch** that you can use to add an asset outside of the module system.
 
-## Adding Assets Outside of the Module System
+## Adding assets outside of the module system
 
-You can create a folder named `static` at the root of your project. Every file
-you put into that folder will be copied into the `public` folder. E.g. if you
-add a file named `sun.jpg` to the static folder, it'll be copied to
-`public/sun.jpg`
+You can create a folder named `static` at the root of your project. Every file you put into that folder will be copied into the `public` folder. E.g. if you add a file named `sun.jpg` to the static folder, it'll be copied to `public/sun.jpg`
 
 ### 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):
+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):
 
 ```js
 import { withPrefix } from 'gatsby'
@@ -38,8 +30,7 @@ render() {
 }
 ```
 
-And make sure you
-[set `pathPrefix` in your gatsby-config.js](/docs/path-prefix/):
+And make sure you [set `pathPrefix` in your gatsby-config.js](/docs/path-prefix/):
 
 ```javascript:title=gatsby-config.js
 module.exports = {
@@ -52,16 +43,13 @@ module.exports = {
 
 Keep in mind the downsides of this approach:
 
-- None of the files in `static` folder get post-processed or minified.
-- Missing files will not be called at compilation time, and will cause 404
-  errors for your users.
-- Result filenames won’t include content hashes so you’ll need to add query
-  arguments or rename them every time they change.
+- None of the files in `static` folder be post-processed or minified.
+- Missing files will not be called at compilation time, and will cause 404 errors for your users.
+- Result filenames won’t include content hashes so you’ll need to add query arguments or rename them every time they change.
 
-## When to Use the `static` Folder
+## When to use the `static` folder
 
-Normally we recommend importing [stylesheets](/docs/adding-images-fonts-files/#adding-a-stylesheet),
-[images, and fonts](/docs/adding-images-fonts-files/#adding-images-and-fonts) from JavaScript. The `static`
+Normally we recommend importing [stylesheets, images, and font assets](/docs/importing-assets-into-files/) from JavaScript. The `static`
 folder is useful as a workaround for a number of less common cases:
 
 - You need a file with a specific name in the build output, such as
@@ -70,5 +58,4 @@ folder is useful as a workaround for a number of less common cases:
 - You want to include a small script like
   [`pace.js`](http://github.hubspot.com/pace/docs/welcome/) outside of the
   bundled code.
-- Some libraries may be incompatible with Webpack and you have no other option but
-  to include it as a `<script>` tag.
+- Some libraries may be incompatible with Webpack and you have no other option but to include it as a `<script>` tag.
diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
index ba052d1ccd84c..ca1a3ccf98df9 100644
--- a/www/src/data/sidebars/doc-links.yaml
+++ b/www/src/data/sidebars/doc-links.yaml
@@ -72,22 +72,22 @@
         - title: Images, Video, and Files
           link: /docs/images-and-files/
           items:
-            - title: Adding Images, Fonts, and Files
-              link: /docs/adding-images-fonts-files/
-            - title: Working With Video
-              link: /docs/working-with-video/
+            - title: Importing Assets Into Files
+              link: /docs/importing-assets-into-files/
             - title: Using the Static Folder
               link: /docs/static-folder/
-            - title: Importing Media Content
-              link: /docs/importing-media-content/
-            - title: gatsby-source-filesystem Programmatic Import*
-              link: /docs/gatsby-source-filesystem-programmatic-import/
             - title: Working with Images in Gatsby
               link: /docs/working-with-images/
             - title: Using gatsby-image
               link: /docs/using-gatsby-image/
             - title: Preoptimizing your Images
               link: /docs/preoptimizing-images/
+            - title: gatsby-source-filesystem Programmatic Import*
+              link: /docs/gatsby-source-filesystem-programmatic-import/
+            - title: Working With Video
+              link: /docs/working-with-video/
+            - title: Importing Media Content
+              link: /docs/importing-media-content/
         - title: Sourcing Content and Data
           link: /docs/content-and-data/
           items:

From 1cb4767e6ac2db400c38b11fd8f960ab05902f62 Mon Sep 17 00:00:00 2001
From: Marcy Sutton <marcy.sutton@deque.com>
Date: Fri, 5 Apr 2019 15:39:56 -0700
Subject: [PATCH 2/8] add redirect for adding-images-fonts-files page

---
 www/gatsby-node.js | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/www/gatsby-node.js b/www/gatsby-node.js
index 60128c67e26b2..0de8d3b6db740 100644
--- a/www/gatsby-node.js
+++ b/www/gatsby-node.js
@@ -195,6 +195,12 @@ exports.createPages = ({ graphql, actions, reporter }) => {
     isPermanent: true,
   })
 
+  createRedirect({
+    fromPath: `/docs/adding-images-fonts-files`,
+    toPath: `/docs/importing-assets-into-files`,
+    isPermanent: true,
+  })
+
   createRedirect({
     fromPath: `/blog/2019-10-03-gatsby-perf`,
     toPath: `/blog/2018-10-03-gatsby-perf`,

From 925243a8b863fa9999f07b9e7d5ee26ddb8e7024 Mon Sep 17 00:00:00 2001
From: Marcy Sutton <marcy.sutton@deque.com>
Date: Mon, 8 Apr 2019 18:24:13 -0700
Subject: [PATCH 3/8] improve formatting in import doc, add link

---
 docs/docs/importing-assets-into-files.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/docs/importing-assets-into-files.md b/docs/docs/importing-assets-into-files.md
index ba9e1be347f42..d8a9aaa744ed9 100644
--- a/docs/docs/importing-assets-into-files.md
+++ b/docs/docs/importing-assets-into-files.md
@@ -6,10 +6,10 @@ There are two major ways to import assets, such as images, fonts, and files, int
 
 ## Importing assets with Webpack
 
-With Webpack you can **`import` a file right in a JavaScript module**. This tells Webpack to include that file in the bundle. Unlike CSS imports, importing a file gives you a string value. This value is the final path you can reference in your code, e.g. as the `src` attribute of an image or the `href` of a link to a PDF.
+With Webpack you can **`import` a file right in a JavaScript module**. This tells Webpack to include that file in the bundle. Unlike CSS imports, importing a file gives you a string value. This imported file's value is the final path you can reference in your code, e.g. as the `src` attribute of an image or the `href` of a link to a PDF.
 
 To reduce the number of requests to the server, importing images that are less than 10,000 bytes returns a
-[data URI](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) instead of a path. This applies to the following file extensions: svg, jpg, jpeg, png, gif, mp4, webm, wav, mp3, m4a, aac, and oga.
+[data URI](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) instead of a path. This applies to the following file extensions: `svg`, `jpg`, `jpeg`, `png`, `gif`, `mp4`, `webm`, `wav`, `mp3`, `m4a`, `aac`, and `oga`.
 
 Here's an example:
 
@@ -49,9 +49,9 @@ Two alternative ways of handling static assets are described in the next section
 
 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.
 
-Examples:
+### Examples:
 
-- Copy all `.pdf` files you have in your data layer to your build directory and return URLs to them:
+1. Copy all `.pdf` files you have in your data layer to your build directory and return URLs to them:
 
 ```graphql
 {
@@ -65,9 +65,7 @@ Examples:
 }
 ```
 
-- Copy post attachments defined in your Markdown files:
-
-  Link to your attachments in the markdown front matter:
+2. Link to attachments in your Markdown files:
 
 ```markdown
 ---
@@ -80,7 +78,7 @@ attachments:
 Hi, this is a great article.
 ```
 
-In the article template component file, you can query for the attachments:
+In the article template component file, you can then query for the attachments:
 
 ```graphql
 query($slug: String!) {
@@ -95,3 +93,5 @@ query($slug: String!) {
   }
 }
 ```
+
+Read more about querying for files in [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/).

From 1441fc0bf2c6a312cd2edc70e138e5cd3d5a200d Mon Sep 17 00:00:00 2001
From: Marcy Sutton <marcy.sutton@deque.com>
Date: Mon, 8 Apr 2019 18:24:32 -0700
Subject: [PATCH 4/8] remove stub from docs sidebar

this doc seems covered by other docs
---
 www/src/data/sidebars/doc-links.yaml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
index ca1a3ccf98df9..6bb3b5387fd2b 100644
--- a/www/src/data/sidebars/doc-links.yaml
+++ b/www/src/data/sidebars/doc-links.yaml
@@ -82,8 +82,6 @@
               link: /docs/using-gatsby-image/
             - title: Preoptimizing your Images
               link: /docs/preoptimizing-images/
-            - title: gatsby-source-filesystem Programmatic Import*
-              link: /docs/gatsby-source-filesystem-programmatic-import/
             - title: Working With Video
               link: /docs/working-with-video/
             - title: Importing Media Content

From 1f16fdb1722726c46e2555f4d1c7dec6d6a3134b Mon Sep 17 00:00:00 2001
From: Marcy Sutton <marcy.sutton@deque.com>
Date: Mon, 8 Apr 2019 18:24:50 -0700
Subject: [PATCH 5/8] add start to using-gatsby-image docs overhaul

---
 .../src/components/layout.js                  |  9 ++++---
 .../src/components/navigation.js              |  4 +--
 .../src/pages/background-color.js             | 17 ++++++++++---
 .../using-gatsby-image/src/pages/blur-up.js   | 25 ++++++++++++++++---
 .../src/pages/prefer-webp.js                  | 19 +++++++++++---
 .../src/pages/traced-svg.js                   | 22 ++++++++++++----
 6 files changed, 74 insertions(+), 22 deletions(-)

diff --git a/examples/using-gatsby-image/src/components/layout.js b/examples/using-gatsby-image/src/components/layout.js
index 00a6d56ff3900..1a1600de29161 100644
--- a/examples/using-gatsby-image/src/components/layout.js
+++ b/examples/using-gatsby-image/src/components/layout.js
@@ -110,12 +110,15 @@ const Layout = ({ children, image, imageTitle, imageBackgroundColor }) => (
           {` `} for documentation on using the plugin
         </li>
         <li>
-          Read the docs on
-          {` `}“
+          Read the docs:
+          <br />
           <a href="https://www.gatsbyjs.org/docs/using-gatsby-image/">
             Using gatsby-image to prevent image bloat
           </a>
-          ”
+          <br />
+          <a href="https://www.gatsbyjs.org/packages/gatsby-plugin-sharp/">
+            Using fragments in gatsby-plugin-sharp
+          </a>
         </li>
         <li>
           View the <code>gatsby-transformer-sharp</code> example at
diff --git a/examples/using-gatsby-image/src/components/navigation.js b/examples/using-gatsby-image/src/components/navigation.js
index 25a9410a9e1e0..84a60cc219901 100644
--- a/examples/using-gatsby-image/src/components/navigation.js
+++ b/examples/using-gatsby-image/src/components/navigation.js
@@ -1,7 +1,7 @@
 import React from "react"
 import { Link } from "gatsby"
 import styled, { css } from "react-emotion"
-import { MdLaunch } from "react-icons/md"
+import { MdLink } from "react-icons/md"
 
 import { scale, rhythm, options } from "../utils/typography"
 import { mq, elevation, gutter, colors, animation } from "../utils/presets"
@@ -154,7 +154,7 @@ const NavItem = ({ title, to }) => (
   </NavListItem>
 )
 
-const ExternalLinkIcon = styled(MdLaunch)`
+const ExternalLinkIcon = styled(MdLink)`
   background-image: none;
   bottom: -0.2em;
   color: ${colors.gatsby};
diff --git a/examples/using-gatsby-image/src/pages/background-color.js b/examples/using-gatsby-image/src/pages/background-color.js
index 033f50d21f1fd..17ef31a9ec414 100644
--- a/examples/using-gatsby-image/src/pages/background-color.js
+++ b/examples/using-gatsby-image/src/pages/background-color.js
@@ -1,8 +1,6 @@
 import React from "react"
 import { graphql } from "gatsby"
 import Img from "gatsby-image"
-import Lorem from "../components/lorem"
-import Ipsum from "../components/ipsum"
 import FloatingImage from "../components/floating-image"
 import PageTitle from "../components/page-title"
 import Layout from "../components/layout"
@@ -25,7 +23,19 @@ const BackgroundColor = ({ data, location }) => (
       } (via unsplash.com)`}
       backgroundColor="#DB3225"
     />
-    <Lorem />
+    <p>
+      With the Background Color technique, you can specify a CSS background
+      color to fill the space as your images download. For graphic images with a
+      predominant color in the foreground or background, a matching color in the
+      loading space can create a visually pleasing image load experience.
+    </p>
+    <p>
+      To use the Background Color technique, provide a{` `}
+      <code>backgroundColor</code> prop in your floating or fixed image
+      component instance. You can use hex color values, RGB values, or any other
+      valid CSS background color format.
+    </p>
+
     <Img
       fluid={data.fullWidthImage.localFile.childImageSharp.fluid}
       backgroundColor="#F9D6CE"
@@ -33,7 +43,6 @@ const BackgroundColor = ({ data, location }) => (
         data.fullWidthImage.credit
       } (via unsplash.com)`}
     />
-    <Ipsum />
   </Layout>
 )
 
diff --git a/examples/using-gatsby-image/src/pages/blur-up.js b/examples/using-gatsby-image/src/pages/blur-up.js
index 7560a5c2c23ed..33f505c8dc6dc 100644
--- a/examples/using-gatsby-image/src/pages/blur-up.js
+++ b/examples/using-gatsby-image/src/pages/blur-up.js
@@ -2,8 +2,6 @@ import React from "react"
 import { graphql } from "gatsby"
 import Img from "gatsby-image"
 
-import Lorem from "../components/lorem"
-import Ipsum from "../components/ipsum"
 import FloatingImage from "../components/floating-image"
 import PageTitle from "../components/page-title"
 import Layout from "../components/layout"
@@ -25,14 +23,33 @@ const BlurUp = ({ data, location }) => (
       } (via unsplash.com)`}
     />
 
-    <Lorem />
+    <p>
+      The default Blur Up technique uses progressive loading to make a fast,
+      visually pleasing experience without waiting for a full-resolution image
+      with a blank screen.
+    </p>
+    <h2>Progressive Loading with Minimal Effort</h2>
+    <p>
+      The magic of Gatsby Image's Blur Up technique means that you can load an
+      image at moderate resolution and not have to bother with creating a small
+      thumbnail yourself. Gatsby Image will automatically create a tiny image
+      from your source image and load it first for quick display while the
+      larger image file is downloaded and displayed. Users first see a blurry
+      lower-resolution image to help with perceived performance, while the
+      larger image downloads and everything works automatically.
+    </p>
+    <p>
+      This technique is the default behavior when querying for an image with
+      QraphQL and providing a fragment like <code>GatsbyImageSharpFixed</code>.
+      If you don’t want to use the blur-up effect, choose a fragment with{` `}
+      <code>noBase64</code> at the end.
+    </p>
     <Img
       fluid={data.fullWidthImage.localFile.childImageSharp.fluid}
       title={`“${data.fullWidthImage.title}” by ${
         data.fullWidthImage.credit
       } (via unsplash.com)`}
     />
-    <Ipsum />
   </Layout>
 )
 
diff --git a/examples/using-gatsby-image/src/pages/prefer-webp.js b/examples/using-gatsby-image/src/pages/prefer-webp.js
index 20321aa439cf2..660e6111b3c7b 100644
--- a/examples/using-gatsby-image/src/pages/prefer-webp.js
+++ b/examples/using-gatsby-image/src/pages/prefer-webp.js
@@ -5,8 +5,6 @@ import Img from "gatsby-image"
 import FloatingImage from "../components/floating-image"
 import PageTitle from "../components/page-title"
 import Layout from "../components/layout"
-import Ipsum from "../components/ipsum"
-import Lorem from "../components/lorem"
 
 const PreferWebp = ({ data, location }) => (
   <Layout
@@ -24,14 +22,27 @@ const PreferWebp = ({ data, location }) => (
         data.floatingImage.credit
       } (via unsplash.com)`}
     />
-    <Lorem />
+    <p>
+      WebP is a modern image format that provides both lossless and lossy
+      compression for images on the web. This format can reduce the filesize
+      considerably compared to JPG and PNG files, and using it is pretty easy
+      with <strong>gatsby-image</strong> and{` `}
+      <strong>gatsby-plugin-sharp</strong>.
+    </p>
+    <p>
+      The <strong>WebP</strong> technique is similar to other gatsby-image
+      techniques in that it can be applied in image queries with GraphQL. To
+      specify that an image should be loaded in the WebP format in supporting
+      browsers, use a fragment with
+      <code>withWebp</code> at the end.
+    </p>
     <Img
       fluid={data.fullWidthImage.localFile.childImageSharp.fluid}
       title={`“${data.fullWidthImage.title}” by ${
         data.fullWidthImage.credit
       } (via unsplash.com)`}
     />
-    <Ipsum />
+    <p />
   </Layout>
 )
 
diff --git a/examples/using-gatsby-image/src/pages/traced-svg.js b/examples/using-gatsby-image/src/pages/traced-svg.js
index a871e9c44c0a4..2995e7eebb2ad 100644
--- a/examples/using-gatsby-image/src/pages/traced-svg.js
+++ b/examples/using-gatsby-image/src/pages/traced-svg.js
@@ -2,8 +2,6 @@ import React from "react"
 import { graphql } from "gatsby"
 import Img from "gatsby-image"
 
-import Lorem from "../components/lorem"
-import Ipsum from "../components/ipsum"
 import FloatingImage from "../components/floating-image"
 import PageTitle from "../components/page-title"
 import ImageGallery from "../components/image-gallery"
@@ -26,10 +24,24 @@ const TracedSVG = ({ data, location }) => (
         data.floatingImage.credit
       } (via unsplash.com)`}
     />
-    <Lorem />
-    <h2>Unsplash</h2>
+    <p>
+      Generates a{` `}
+      <a href="https://github.com/gatsbyjs/gatsby/issues/2435">traced SVG</a> of
+      the image and returns the SVG source as an ”optimized URL-encoded” data:
+      URI. This provides an alternative to the default inline base64 placeholder
+      image.
+    </p>
+    <p>
+      To make use of this technique, you can apply processing to an image with a
+      GraphQL query by applying a <code>traceSVG</code> argument and the
+      appropriate{` `}
+      <a href="https://www.gatsbyjs.org/packages/gatsby-image/#gatsby-transformer-sharp">
+        fragment applied
+      </a>
+      .
+    </p>
+    <h2>Unsplash SVG Image Gallery</h2>
     <ImageGallery images={data.galleryImages.edges} />
-    <Ipsum />
     <Img
       fluid={data.fullWidthImage.localFile.childImageSharp.fluid}
       title={`“${data.fullWidthImage.title}” by ${

From b823da51c21a7678f9f1ad3bfb8e6a47e045b65d Mon Sep 17 00:00:00 2001
From: Marcy Sutton <marcy.sutton@deque.com>
Date: Mon, 15 Apr 2019 16:27:11 -0700
Subject: [PATCH 6/8] rename/rearrange docs to be more descriptive

---
 docs/docs/images-and-files.md        | 4 ++--
 www/src/data/sidebars/doc-links.yaml | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/docs/images-and-files.md b/docs/docs/images-and-files.md
index 13c4b49b15afc..59d2de46775cc 100644
--- a/docs/docs/images-and-files.md
+++ b/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]]
diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
index 65732b0f6ad0b..0f2a8e6163c85 100644
--- a/www/src/data/sidebars/doc-links.yaml
+++ b/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

From 9c086a45bc0f24428179b0dae8edff577147c50b Mon Sep 17 00:00:00 2001
From: Marcy Sutton <marcy.sutton@deque.com>
Date: Mon, 15 Apr 2019 16:27:39 -0700
Subject: [PATCH 7/8] copy updates

Closes https://github.com/gatsbyjs/gatsby/issues/13297
---
 docs/docs/importing-assets-into-files.md | 53 ++++++++++++++++++++----
 docs/docs/static-folder.md               | 15 +------
 docs/docs/using-gatsby-image.md          | 12 +++---
 docs/docs/working-with-images.md         |  2 +-
 4 files changed, 55 insertions(+), 27 deletions(-)

diff --git a/docs/docs/importing-assets-into-files.md b/docs/docs/importing-assets-into-files.md
index d8a9aaa744ed9..a50b33bb24667 100644
--- a/docs/docs/importing-assets-into-files.md
+++ b/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!) {
diff --git a/docs/docs/static-folder.md b/docs/docs/static-folder.md
index f8b1babe761fd..aafcaa580b987 100644
--- a/docs/docs/static-folder.md
+++ b/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" />;
 }
 ```
 
diff --git a/docs/docs/using-gatsby-image.md b/docs/docs/using-gatsby-image.md
index 4e2221c77bd8e..478b6cabd391a 100644
--- a/docs/docs/using-gatsby-image.md
+++ b/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"
diff --git a/docs/docs/working-with-images.md b/docs/docs/working-with-images.md
index 4c8027dffa8cb..8980cd0f0dff7 100644
--- a/docs/docs/working-with-images.md
+++ b/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

From 00f2ee07cd8266b59947334fb2d709356c149638 Mon Sep 17 00:00:00 2001
From: Marcy Sutton <marcy.sutton@deque.com>
Date: Tue, 16 Apr 2019 10:34:30 -0700
Subject: [PATCH 8/8] update comment to reflect page change

---
 docs/docs/static-folder.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/docs/static-folder.md b/docs/docs/static-folder.md
index aafcaa580b987..def6d61efa9c9 100644
--- a/docs/docs/static-folder.md
+++ b/docs/docs/static-folder.md
@@ -23,7 +23,7 @@ You can reference assets from the `static` folder in your code without anything
 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.
+  // as described in the “Importing Assets Directly Into Files” page.
   return <img src={'logo.png'} alt="Logo" />;
 }
 ```