gatsbyjs · marcysutton · Jun 12, 2019 · Jun 11, 2019 · Jun 11, 2019 · Jun 11, 2019
diff --git a/docs/docs/gatsby-config.md b/docs/docs/gatsby-config.md
@@ -1,5 +1,5 @@
 ---
-title: Gatsby Config
+title: Gatsby Config API
 ---
 
 Site configuration options for a Gatsby site are placed in a file at the root of the project folder called `gatsby-config.js`.

diff --git a/docs/docs/gatsby-image.md b/docs/docs/gatsby-image.md
diff --git a/docs/docs/gatsby-link.md b/docs/docs/gatsby-link.md
@@ -1,5 +1,5 @@
 ---
-title: Gatsby Link
+title: Gatsby Link API
 ---
 
 For internal navigation, Gatsby includes a built-in `<Link>` component as well as a `navigate` function which is used for programmatic navigation.

diff --git a/docs/docs/images-and-files.md b/docs/docs/images-and-files.md
@@ -1,8 +1,9 @@
 ---
-title: Images, Files, and Video
-overview: true
+title: Images, Files, and Video in Gatsby
 ---
 
-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.
+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/importing-assets-into-files/) and use of the [static folder](/docs/static-folder/) to dynamic queries with [Gatsby Image](/docs/using-gatsby-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.
 
 <GuideList slug={props.slug} />
diff --git a/docs/docs/images/dancing-otter.gif b/docs/docs/images/dancing-otter.gif
diff --git a/docs/docs/images/duotone-before-after.png b/docs/docs/images/duotone-before-after.png
diff --git a/docs/docs/images/grayscale-before-after.png b/docs/docs/images/grayscale-before-after.png
diff --git a/docs/docs/using-gatsby-image.md b/docs/docs/using-gatsby-image.md
@@ -1,9 +1,7 @@
 ---
-title: Using Gatsby Image
+title: Using Gatsby Image to Prevent Image Bloat
 ---
 
-# Using gatsby-image to prevent image bloat
-
 `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._
@@ -16,6 +14,8 @@ title: Using Gatsby Image
 - holds an image’s position so your page doesn’t jump around as images load
 - makes it easy to add a placeholder—either a gray background or a blurry version of the image.
 
+_For more complete API information, check out the [Gatsby Image API](/docs/gatsby-image/) docs._
+
 ## Problem
 
 Large, unoptimized images dramatically slow down your site.
@@ -105,11 +105,12 @@ export default ({ data }) => (
 
 This GraphQL query creates multiple sizes of the image and when the page is rendered the image that is appropriate for the current screen resolution (e.g. desktop, mobile, and everything in between) is used. The `gatsby-image` component automatically enables a blur-up effect as well as lazy loading images that are not currently on screen.
 
-So this is all very nice and it’s far better to be able to use this from NPM vs. implementing it yourself or cobbling together several standalone libraries.
+So this is all very nice and it’s far better to be able to use this from npm vs. implementing it yourself or cobbling together several standalone libraries.
 
-### References:
+### Additional resources
 
-- [Gatsby image plugin README file](/packages/gatsby-image/)
+- [Gatsby Image API docs](/docs/gatsby-image/)
+- [gatsby-image plugin README file](/packages/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)

diff --git a/docs/docs/working-with-gifs.md b/docs/docs/working-with-gifs.md
@@ -0,0 +1,42 @@
+---
+title: Working With GIFs
+---
+
+If you're building a blog with Gatsby, chances are you'll want to include some animated GIFs: who wouldn't want to include a dancing otter or cat GIF?
+
+## Including GIFs in components
+
+In Gatsby components and pages, you'll want to import animated GIFs instead of using Gatsby Image because of the way it optimizes image data for the responsive picture element.
+
+Here's an example:
+
+```jsx:title=pages/about.js
+import React from 'react'
+
+import Layout from '../components/layout'
+import otterGIF from '../gifs/otter.gif'
+
+const AboutPage = () => (
+    return (
+        <Layout>
+            <img src={otterGIF} alt="Otter dancing with a fish" />
+        </Layout>
+    )
+)
+
+export default AboutPage;
+```
+
+## Including GIFs in Markdown
+
+In Markdown posts and pages, including an animated GIF is the same as a static image:
+
+```markdown
+![otter dancing with a fish](./images/dancing-ofter.gif)
+```
+
+![otter dancing with a fish](./images/dancing-otter.gif)
+
+Animated GIFs can be quite large in size, however, so be careful not to sabotage your webpages' performance with extremely large files. You could reduce file size by [optimizing the frames](https://skylilies.livejournal.com/244378.html) or converting them to video.
+
+> Note: beware that flashing and autoplaying GIFs can cause accessibility problems. One technique would be to add controls, such as using a package like [react-gif-player](https://www.npmjs.com/package/react-gif-player).
diff --git a/docs/docs/working-with-images.md b/docs/docs/working-with-images.md
@@ -90,3 +90,10 @@ export const query = graphql`
   }
 `
 ```
+
+### Additional resources
+
+- [Gatsby Image API docs](/docs/gatsby-image/)
+- [gatsby-image plugin README file](/packages/gatsby-image/)
+- [gatsby-plugin-sharp README file](/packages/gatsby-plugin-sharp/)
+- [gatsby-transformer-sharp README file](/packages/gatsby-transformer-sharp/)
diff --git a/packages/gatsby-image/README.md b/packages/gatsby-image/README.md
@@ -10,7 +10,7 @@ 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
+_Note: 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._
 
@@ -340,7 +340,7 @@ You will need to add it in your graphql query as is shown in the following snipp
 | `fadeIn`               | `bool`              | Defaults to fading in the image on load                                                                                     |
 | `durationFadeIn`       | `number`            | fading duration is set up to 500ms by default                                                                               |
 | `title`                | `string`            | Passed to the `img` element                                                                                                 |
-| `alt`                  | `string`            | Passed to the `img` element                                                                                                 |
+| `alt`                  | `string`            | Passed to the `img` element. Defaults to an empty string `alt=""`                                                           |
 | `crossOrigin`          | `string`            | Passed to the `img` element                                                                                                 |
 | `className`            | `string` / `object` | Passed to the wrapper element. Object is needed to support Glamor's css prop                                                |
 | `style`                | `object`            | Spread into the default styles of the wrapper element                                                                       |

diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
@@ -88,6 +88,8 @@
               link: /docs/working-with-video/
             - title: Importing Media Content
               link: /docs/importing-media-content/
+            - title: Working with GIFs
+              link: /docs/working-with-gifs/
         - title: Sourcing Content and Data
           link: /docs/content-and-data/
           items:
@@ -347,6 +349,8 @@
       items:
         - title: Gatsby Link
           link: /docs/gatsby-link/
+        - title: Gatsby Image
+          link: /docs/gatsby-image/
         - title: Gatsby Config
           link: /docs/gatsby-config/
         - title: Gatsby Node APIs