Gatsby: Simplify using-gatsby-image example

[trepidacious]

Summary

The using-gatsby-image example is complicated and uses multiple features unrelated to gatsby-image. The code related to images is spread across multiple locations. There are few comments.

Basic example

I would suggest that the example is rewritten to:

1. Remove everything that is not completely necessary to demonstrate gatsby-image itself, including styling, layout, the "ipsum" content, etc.
2. Include an example of the most basic use-case: using an image in a file from a component. This would not provide any additional features, styling, requesting external resources, adapting to mobile, etc.
3. Include a comment in code on each part of the basic example explaining it.
4. Point the user to this basic example from the readme.
5. Optionally, include additional examples of more complex use, each in a self-contained component clearly commented to indicate what it is demonstrating and linked from the readme. This would ideally demonstrate only one or two additional features in each example, with the minimum complexity needed to show that feature.

Motivation

This would help to bring the gatsby-image documentation up to the very high level of the step by step tutorial.

This would provide a minimal example for users who may be struggling with getting gatsby-image to work, that they can then build on with additional features. Each existing example I can find (and it's good that there are a lot) is quite long, covering a wide range of features, and does not include a self-contained, minimal, commented, functional example.

The expected outcome would be that users could completely understand the example, and then copy and paste it to their own project to establish a baseline use of images.

This would be achieved by reducing the amount of cognitive overhead in separating out the parts of the example project that are required for gatsby-image from the 90-95% that is unrelated.

[sidharthachatterjee]

cc @shannonbux

[shannonbux]

It's probably important to coordinate this issue with #9374, which deals with adding a gatsby-image tutorial. @marcysutton I think you might be interested in following improvements to how people learn about and use gatsby-image. Far too many people are unaware of it!

[marcysutton]

I too am struggling with gatsby-image, so this is a great proposal!

[shannonbux]

Same here! Trying to get it working for my sister's site, and looking through tons of people's source code hasn't quite helped me find a use case that matches mine (which is pretty simple. I'm just trying to use gatsby-image in my layout.js file to make the logo image load with a nice background color and I'm not really a developer so any amount of complexity in source code means I don't know how to imitate it)

Because the gatsby-image example site is so complex, I think it would make sense to clone it and then create a stripped down version, and then rename the complex version. Or perhaps add a simple "practice page" to the site. @fk is the creator so looping him in here.

They could be called
using-gatsby-image-advanced
using-gatsby-image

[fk]

Hey @trepidacious (and everyone)! Thanks for opening this issue and your detailed description!

I hear you (and everyone 😉) loud and clear. I agree that using-gatsby-image is not a minimal example, and that we need the latter (looking at #9374 makes me want to add "in one form or another").

@jlengstorf's outline for the potential new part in the tutorial looks great, https://github.com/gatsbyjs/gatsby/issues/9374#issuecomment-433088391, but maybe it's a bit too much to tackle in one go? How about we expand https://www.gatsbyjs.org/docs/using-gatsby-image/#solution to include all necessary steps in the meantime?
Quoting from Jason's list those steps would be

• Show how to install gatsby-image and it's peer dependencies
• Configure the peer deps to load images from a folder
• Write a query to load the image data for gatsby-image

[laurieontech]

I'm happy to take this on. I recently wrote up something similar for a blog post, so easy enough to adapt.

[jlengstorf]

it's peer dependencies

Ugh I can't believe I made that typo. 😭

@lstar19 we’d love to have your help! @marcysutton is there anything to keep in mind here, or is this ready for a PR?

[marcysutton]

I think this issue can be closed now that #11998 was merged! Please let us know if it could be simplified further.