[docs][recipes] images with webpack and from static folder (#15813)

* chore: add example and recipe for images with the static folder #14986

* chore: add example and recipe for importing image with webpack #14985

* chore: update content in example readme, make example match inline code

* fixing TOC, a few content updates

* chore: apply suggestions to examples from code review

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

docs/docs/recipes.md

@@ -597,7 +597,87 @@ export default NonPageComponent
 
 ## 7. Working with images
 
-Coming soon!
+### Import an image into a component with webpack
+
+Images can be imported right into a JavaScript module with webpack. This process automatically minifies and copies the image to your site's `public` folder, providing a dynamic image URL for you to pass to an HTML `<img>` element like a regular file path.
+
+#### Prerequisites
+
+- A [Gatsby Site](/docs/quick-start) with a `.js` file exporting a React component
+- an image (`.jpg`, `.png`, `.gif`, `.svg`, etc.) in the `src` folder
+
+#### Directions
+
+1. Import your file from its path in the `src` folder:
+
+```jsx:title=src/pages/index.js
+import React from "react"
+// Tell webpack this JS file uses this image
+import FiestaImg from "../assets/fiesta.jpg" // highlight-line
+```
+
+2. In `index.js`, add an `<img>` tag with the `src` as the name of the import you used from webpack (in this case `FiestaImg`), and add an `alt` attribute [describing the image](https://webaim.org/techniques/alttext/):
+
+```jsx:title=src/pages/index.js
+import React from "react"
+import FiestaImg from "../assets/fiesta.jpg"
+
+export default () => (
+  // The import result is the URL of your image
+  <img src={FiestaImg} alt="A dog smiling in a party hat" /> // highlight-line
+)
+```
+
+3. Run `gatsby develop` to start the development server.
+4. View your image in the browser: `http://localhost:8000/`
+
+#### Additional resources
+
+- [Example repo importing an image with webpack](https://github.com/gatsbyjs/gatsby/tree/master/examples/recipe-webpack-image)
+- [More on all image techniques in Gatsby](/docs/images-and-files/)
+
+### Reference an image from the `static` folder
+
+As an alternative to importing assets with webpack, the `static` folder allows access to content that gets automatically copied into the `public` folder when built.
+
+This is an **escape route** for [specific use cases](/docs/static-folder/#when-to-use-the-static-folder), and other methods like [importing with webpack](#import-an-image-into-a-component-with-webpack) are recommended to leverage optimizations made by Gatsby.
+
+#### Prerequisites
+
+- A [Gatsby Site](/docs/quick-start) with a `.js` file exporting a React component
+- An image (`.jpg`, `.png`, `.gif`, `.svg`, etc.) in the `static` folder
+
+#### Directions
+
+1. Ensure that the image is in your `static` folder at the root of the project. Your project structure might look something like this:
+
+```
+├── gatsby-config.js
+├── src
+│   └── pages
+│       └── index.js
+├── static
+│       └── fiesta.jpg
+```
+
+2. In `index.js`, add an `<img>` tag with the `src` as the relative path of the file from the `static` folder, and add an `alt` attribute [describing the image](https://webaim.org/techniques/alttext/):
+
+```jsx:title=src/pages/index.js
+import React from "react"
+
+export default () => (
+  <img src={`fiesta.jpg`} alt="A dog smiling in a party hat" /> // highlight-line
+)
+```
+
+3. Run `gatsby develop` to start the development server.
+4. View your image in the browser: `http://localhost:8000/`
+
+#### Additional resources
+
+- [Example repo referencing an image from the static folder](https://github.com/gatsbyjs/gatsby/tree/master/examples/recipe-static-image)
+- [Using the Static Folder](/docs/static-folder/)
+- [More on all image techniques in Gatsby](/docs/images-and-files/)
 
 ## 8. Transforming data
 

examples/recipe-static-image/.gitignore

@@ -0,0 +1,69 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# dotenv environment variables file
+.env
+
+# gatsby files
+.cache/
+public
+
+# Mac files
+.DS_Store
+
+# Yarn
+yarn-error.log
+.pnp/
+.pnp.js
+# Yarn Integrity file
+.yarn-integrity

examples/recipe-static-image/README.md

@@ -0,0 +1,3 @@
+# Referencing an image from the static folder
+
+Example site based on the recipe in the docs on adding an image to a site from the static foldere

examples/recipe-static-image/gatsby-config.js

@@ -0,0 +1,9 @@
+/**
+ * Configure your Gatsby site with this file.
+ *
+ * See: https://www.gatsbyjs.org/docs/gatsby-config/
+ */
+
+module.exports = {
+  /* Your site config here */
+}

examples/recipe-static-image/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "recipe-static-image",
+  "private": true,
+  "description": "A recipe example on using Gatsby's static folder for images",
+  "version": "0.1.0",
+  "license": "MIT",
+  "scripts": {
+    "build": "gatsby build",
+    "develop": "gatsby develop",
+    "format": "prettier --write src/**/*.{js,jsx}",
+    "start": "npm run develop",
+    "serve": "gatsby serve",
+    "test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\""
+  },
+  "dependencies": {
+    "gatsby": "^2.13.25",
+    "react": "^16.8.6",
+    "react-dom": "^16.8.6"
+  },
+  "devDependencies": {
+    "prettier": "^1.18.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gatsbyjs/gatsby-starter-hello-world"
+  },
+  "bugs": {
+    "url": "https://github.com/gatsbyjs/gatsby/issues"
+  }
+}

examples/recipe-static-image/src/pages/index.js

@@ -0,0 +1,5 @@
+import React from "react"
+
+export default () => (
+  <img src={`fiesta.jpg`} alt="Dogs in party hats celebrating at an event" />
+)

examples/recipe-webpack-image/.gitignore

@@ -0,0 +1,69 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# dotenv environment variables file
+.env
+
+# gatsby files
+.cache/
+public
+
+# Mac files
+.DS_Store
+
+# Yarn
+yarn-error.log
+.pnp/
+.pnp.js
+# Yarn Integrity file
+.yarn-integrity

examples/recipe-webpack-image/README.md

@@ -0,0 +1,3 @@
+# Importing an image with webpack
+
+Example site based on the recipe in the Gatsby docs on importing an image to a site using webpack

examples/recipe-webpack-image/gatsby-config.js

@@ -0,0 +1,9 @@
+/**
+ * Configure your Gatsby site with this file.
+ *
+ * See: https://www.gatsbyjs.org/docs/gatsby-config/
+ */
+
+module.exports = {
+  /* Your site config here */
+}

examples/recipe-webpack-image/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "recipe-webpack-image",
+  "private": true,
+  "description": "A recipe example showing how to import images with webpack",
+  "version": "0.1.0",
+  "license": "MIT",
+  "scripts": {
+    "build": "gatsby build",
+    "develop": "gatsby develop",
+    "format": "prettier --write src/**/*.{js,jsx}",
+    "start": "npm run develop",
+    "serve": "gatsby serve",
+    "test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\""
+  },
+  "dependencies": {
+    "gatsby": "^2.13.25",
+    "react": "^16.8.6",
+    "react-dom": "^16.8.6"
+  },
+  "devDependencies": {
+    "prettier": "^1.18.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gatsbyjs/gatsby-starter-hello-world"
+  },
+  "bugs": {
+    "url": "https://github.com/gatsbyjs/gatsby/issues"
+  }
+}

examples/recipe-webpack-image/src/pages/index.js

@@ -0,0 +1,6 @@
+import React from "react"
+import FiestaImg from "../assets/fiesta.jpg"
+
+export default () => (
+  <img src={FiestaImg} alt="Dogs in party hats celebrating at an event" />
+)