fix(docs): improve Gatsby Image docs

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
 

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

@@ -0,0 +1,136 @@
+---
+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 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
+
+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`.
+
+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 in CSS to import them, 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.
+
+## Querying for a `File` in GraphQL using gatsby-source-filesystem
+
+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:
+
+1. 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
+      }
+    }
+  }
+}
+```
+
+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
+---
+title: "Title of article"
+attachments:
+  - "./assets.zip"
+  - "./presentation.pdf"
+---
+
+Hi, this is a great article.
+```
+
+In an article template component file, you can then query for the attachments:
+
+```graphql
+query($slug: String!) {
+  markdownRemark(fields: { slug: { eq: $slug } }) {
+    html
+    frontmatter {
+      title
+      attachments {
+        publicURL
+      }
+    }
+  }
+}
+```
+
+Read more about querying for files in [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/).

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).