Tutorial: add gatsby-image

[shannonbux]

Summary

We want to create a new tutorial for gatsby-image for intermediate users. This learning resource should show how to create responsive images step-by-step. It would fit best as the first item on the Additional Tutorials page.

Here's some information on creating tutorials: https://www.gatsbyjs.org/contributing/docs-templates/#tutorials

Motivation

Many Gatsby users don't know about gatsby-image and it's one of the most noticeable benefits to Gatsby site visitors.

@jlengstorf continuing the discussion from #9158 (comment)

[siddhant1]

On it !

[jlengstorf]

All yours, @siddhant1!

@shannonbux Where do you think this should go? My thought is that it might be its own new section after Part 4 that could be called "Using Images in Gatsby".

Things to cover:

• Gatsby can use regular images, just like any other web framework (show a small example)
• Gatsby has tools to automatically optimize images that have been packaged up in gatsby-image
  • lazy loading
  • generation of different sizes
  • optimization to decrease file sizes
  • creation of placeholders
• Explain why these optimizations are important
• 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
• Discuss the different options (e.g. traced SVG, WebP)
• Link to using-gatsby-image.gatsbyjs.org

Anything I'm missing here?

[treb0r]

It would be great to see some documentation on how to leverage an external service such as imgix with gatsby-image, possibly using react-imgix.

[liltechnomancer]

Can I take this?

[siddhant1]

@Ivrbrtsn sure !

[shannonbux]

@lvrbrtsn thanks! See @jlengstorf's comment above. #9374 (comment)

The idea is basically a standalone tutorial on how to put images in a Gatsby site and we can point people to this tutorial after they finish part eight of the current main tutorial. We consider gatsby-image a best practice, but like Jason said, it's important to also teach people the most fundamental and common ways of putting images in Gatsby sites (see the Style Guide for clear reasoning on why we do this).

[harshil1712]

Is anyone working on this? I would like to take this one

[liltechnomancer]

@harshil1712 Feel free! I have not made much progress and have a lot coming up this next month.

[KyleAMathews]

Updated the description to make clear this issue is for a separate tutorial, not to amend the main tutorial.

[harshil1712]

Just to be on the right track, this file should be in the docs folder, right?

[KyleAMathews]

Yup!

[shannonbux]

Yes. It could go under the `Advanced Tutorials` section in the `doc-links.yml` file or potentially under `Images and Files`. The tutorial should assume that the reader has at least gone through the Main Tutorial, or already knows how to do the tasks covered in the Main Tutorial. Thanks!

…

On Sat, Jan 26, 2019 at 8:48 AM Harshil Agrawal ***@***.***> wrote: Just to be on the right track, this file should be in the docs folder, right? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#9374 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ae9o2jPGDrdMCJoib57MUb0_kkqIkweKks5vHIbAgaJpZM4X5Mt5> .

[gatsbot]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

Thanks for being a part of the Gatsby community! 💪💜

[shannonbux]

Don't close!

…

On Fri, Feb 22, 2019 at 9:28 AM gatsbot[bot] ***@***.***> wrote: Hiya! This issue has gone quiet. Spooky quiet. 👻 We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here. If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open! Thanks for being a part of the Gatsby community! 💪💜 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#9374 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ae9o2v0UtnHX0BoPDafalkhXHJX3VgXeks5vQCikgaJpZM4X5Mt5> .

[harshithpabbati]

Was this still there?? Can I work on this ??

[harshil1712]

@harshithpabbati I you want we can work on this together!

[harshithpabbati]

sure @harshil1712 where were you struck???

[marcysutton]

Hey folks, let us know if you need any help starting the new image tutorial! It would be great to move this forward.

[siddhant1]

I was busy with some work earlier. Will work and close this one in a few days

[polarathene]

There is some changes I contributed to gatsby-image recently but didn't get around to documenting yet. Just saw this issue and it might be relevant to mention them.

It was placeholder base64 related, for being able to set a custom width(instead of the default 20px), which can be useful when 20px doesn't "blur-up" well, or if you want to apply an actual CSS blur filter where a little more detail smooths that out nicely. You can find the related PR here.

The other features were less likely to be useful, just like how the base64 width could be global or per image, you could force a base64 image format or use webp(smaller filesize) which works for Chrome/Firefox while using a bgcolor as a fallback for those not supporting webp.

[ghost]

@marcysutton I can help with the image tutorial?

[theNaut1lus]

Hey, Seems like a lot of people have been attempting to work on this, If no one is currently working on the at the moment, I would love to take this up and make this my first contribution here.
@marcysutton @siddhant1 @shannonbux ?

[siddhant1]

Yeah ! Go for it!

[marcysutton]

We would definitely love for someone to take this on! If you're interested in working on it, go for it. Submitting a PR is the best way to move this forward.

The location for this in the docs may move as I'm proposing some changes to the Tutorial section (grouping the main tutorial + advanced tutorials) but that shouldn't impact the content. For ideas on what an image tutorial should cover, you can reference the previous comments from @shannonbux and @jlengstorf:

• Tutorial: add gatsby-image #9374 (comment)
• Tutorial: add gatsby-image #9374 (comment)

[polarathene]

A PR for another feature to gatsby-image is currently in development/review. It adds support for art-direction by supplying an array of fluid/fixed image data, allowing an image to represent multiple variants based on their matching media query condition.

Would be good to include that too, or an update if these docs are finished before the PR is merged.

An example has been linked from the PR author of a recent project they've worked on. It shows how you can make the image responsive to adapt to a suitable portrait variant for mobile vs the landscape variant for desktop/tablet.

[harshil1712]

I found three different articles which cover almost everything. Artilce 1, Article 2, Article 3. Since there's documentation do we need to have a new one? We can give reference to them? If we still need to write a tutorial, will it be fine if I use those?

[marcysutton]

There would likely be some overlap in a gatsby-image tutorial, but it's worth keeping in mind the purpose of tutorials:

Tutorials provide step-by-step guidance for Gatsby workflows, listing all pre-requisites and not assuming knowledge or skipping steps.

A tutorial could guide a user through setting all of this up without the limiting pressure of a reference guide to not be too lengthy. Maybe it would help to think of a tutorial as the written-version of a how-to video. You can certainly start by looking at the content that already exists, but make sure the steps all work in order.

[laurieontech]

I'd be happy to take this on. I'd probably pull a lot from this post if that works?
https://dev.to/laurieontech/rewriting-a-static-website-using-gatsby-and-graphql---part-3-4ho9

[marcysutton]

That sounds great, @lstar19! If you can make it a standalone piece, that would be awesome. I would also recommend using the useStaticQuery hook if possible since it's a little bit simpler to read. Thanks again for offering to work on this. I'm going to assign the issue to you, if that's alright!

[marcysutton]

Closed with #15027. Thanks so much for all the input here!