fix(docs): improve image docs from workflow evaluation #14697

marcysutton · 2019-06-11T00:55:23Z

Description

As part of #14529, this PR introduces more documentation for images in Gatsby. Specifically:

adding Gatsby Image to the API docs as the information was previously spread across multiple docs and plugin READMEs
adding "in gatsby" to the URL and title of the "Images, Files and Video" page for SEO
adding more content to Images, Files and Video page to improve decision making
adding more links to the Using Gatsby Image and Working with Images in Gatsby pages
adding content about working with GIFs

Things still to do:

image recipes (separate issue is [docs] add image docs recipes #14542)
add content about working with multiple images (ultimately the fix is in [feat]: add ability to pass variables to StaticQuery #10482)
incorporate a gatsby-image tutorial (Tutorial: add gatsby-image #9374)

I decided not to add the gatsby-image props, fragments and API info in Reference Guides because that content went into the new API doc instead. Those docs are more conceptual and do include some examples, but they link off to the API doc instead of including all the parameters/methods/etc. It seemed like overkill and potentially confusing to include those in multiple places.

I'm super open to improvements, as this is the first go at the API doc! Let me know if there's anything you feel could be improved or simplified if it's too long. I tried to bring the major components all together into one place but it's a lot of stuff, so I subjectively included what I thought was important to know.

jlengstorf

This is looking great!

docs/docs/gatsby-image-api.md

jlengstorf · 2019-06-11T01:04:57Z

docs/docs/gatsby-image-api.md

+
+## Setting up Gatsby Image
+
+To install Gatsby Image, install the `gatsby-image` package along with necessary plugins `gatsby-transformer-sharp` and `gatsby-plugin-sharp`. Reference the packages in your Gatsby config file. You can also provide additional options to [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp/) in your config file.


Should we include a copy-pasteable block here for convenience?

I debated on that. It's included so many places, I linked to the docs instead. But we could add it if necessary

I ended up adding it in! Thanks for the nudge.

docs/docs/gatsby-image-api.md

jlengstorf · 2019-06-11T01:13:14Z

docs/docs/gatsby-image-api.md

+}
+```
+
+Read more in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/?=#fluid) README.


Suggested change

Read more in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/?=#fluid) README.

Read more in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/#fluid) README.

Anchors don't seem to be working, FYI. 😕

They don't seem to work for me no matter what the URL is...

Actually they do work for me in their existing form, at least locally when I click them. They don't work when deep-linked

docs/docs/gatsby-image-api.md

jlengstorf · 2019-06-11T01:15:31Z

docs/docs/gatsby-image-api.md

+In addition to `gatsby-plugin-sharp` settings in `gatsby-config.js`, there are additional query options that apply to both _fluid_ and _fixed_ images:
+
+- `grayscale` (bool, default: false)
+- `duotone` (bool|obj, default: false)


This might be too much, but a before/after of grayscale and duotone would be dope.

ooh maybe @gillkyle could help me with that!

Here's what I added (note: these images will only be displayed like this if you've upgraded gatsby-remark-images like this PR #14716):

Just pushed right to this branch, feel free to edit it if you want.

you're amazing, thanks @gillkyle !

docs/docs/gatsby-image-api.md

gillkyle

I think this will be really helpful with the additions of the API section as well as a specific page on GIFs 👏

Left some really minor comments.

docs/docs/using-gatsby-image.md

gillkyle · 2019-06-11T15:34:40Z

docs/docs/gatsby-image.md

+
+Additionally, plugins supporting `gatsby-image` currently include [gatsby-source-contentful](/packages/gatsby-source-contentful/), [gatsby-source-datocms](https://github.com/datocms/gatsby-source-datocms) and [gatsby-source-sanity](https://github.com/sanity-io/gatsby-source-sanity). See the [gatsby-image](/packages/gatsby-image/#fragments) README for more details.
+
+## Gatsby-image props


It looks like this info (and maybe some other stuff in this API section are really closely related to what's in the gatsby-image README which this page links to, would it make sense to have the README link back to this page too?

And maybe this table of props is something that could be an MDX component at some point so the two don't diverge (though I'm guessing they don't get updated frequently if at all).

docs/docs/gatsby-image.md

Co-Authored-By: gillkyle <kylerobertgill@gmail.com>

calcsam · 2019-06-11T17:34:34Z

Woooo!

…e api

* add API doc for Gatsby Image, improve API titles * improve content in image docs * add doc on working with GIFs * chore: format * update GIFs page with an animated GIF, for reasons * a few copy tweaks to Gatsby Image API doc * code block tweaks and moving links * add markdown + a11y note to GIFs page * pr feedback from Jason * change warning to a note per feedback * Update docs/docs/using-gatsby-image.md Co-Authored-By: gillkyle <kylerobertgill@gmail.com> * Update docs/docs/gatsby-image.md Co-Authored-By: gillkyle <kylerobertgill@gmail.com> * chore: add example images demonstrating duotone and grayscale in image api * add install code blocks for copy/paste

Marcy Sutton added 4 commits June 10, 2019 17:05

add API doc for Gatsby Image, improve API titles

6c8821b

Merge remote-tracking branch 'origin/master' into image-docs

bf87839

improve content in image docs

a7b61c6

add doc on working with GIFs

f615c3f

marcysutton added the type: documentation An issue or pull request for improving or updating Gatsby's documentation label Jun 11, 2019

marcysutton requested a review from a team as a code owner June 11, 2019 00:55

marcysutton requested a review from a team June 11, 2019 00:55

marcysutton requested a review from a team as a code owner June 11, 2019 00:55

marcysutton added this to In progress in Documentation Roadmap via automation Jun 11, 2019

chore: format

b795e50

prestonso mentioned this pull request Jun 11, 2019

[docs] (meta) Incrementally improve top 25 learning workflows with baseline evaluations #13708

Closed

25 tasks

Marcy Sutton added 3 commits June 10, 2019 18:11

update GIFs page with an animated GIF, for reasons

ab1653d

a few copy tweaks to Gatsby Image API doc

391f662

code block tweaks and moving links

5aff517

jlengstorf reviewed Jun 11, 2019

View reviewed changes

Marcy Sutton added 3 commits June 10, 2019 18:43

add markdown + a11y note to GIFs page

dd04b47

pr feedback from Jason

26814a7

change warning to a note per feedback

7f1c1b6

gillkyle reviewed Jun 11, 2019

View reviewed changes

docs/docs/gatsby-image.md Outdated Show resolved Hide resolved

Marcy Sutton and others added 2 commits June 11, 2019 09:01

Update docs/docs/using-gatsby-image.md

0a0ba3f

Co-Authored-By: gillkyle <kylerobertgill@gmail.com>

Update docs/docs/gatsby-image.md

c6de3a4

Co-Authored-By: gillkyle <kylerobertgill@gmail.com>

gillkyle and others added 3 commits June 11, 2019 16:40

chore: add example images demonstrating duotone and grayscale in imag…

e8f56e8

…e api

Merge remote-tracking branch 'origin/master' into image-docs

ff94864

add install code blocks for copy/paste

e118b04

marcysutton merged commit 16f0baf into master Jun 12, 2019

Documentation Roadmap automation moved this from In progress to Done Jun 12, 2019

marcysutton deleted the image-docs branch June 12, 2019 22:31

marcysutton mentioned this pull request Jun 13, 2019

[docs] [workflows] Working with images #14529

Closed

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(docs): improve image docs from workflow evaluation #14697

fix(docs): improve image docs from workflow evaluation #14697

marcysutton commented Jun 11, 2019

jlengstorf left a comment

jlengstorf Jun 11, 2019

marcysutton Jun 11, 2019

marcysutton Jun 12, 2019

jlengstorf Jun 11, 2019

jlengstorf Jun 11, 2019

marcysutton Jun 12, 2019

marcysutton Jun 12, 2019

jlengstorf Jun 11, 2019

marcysutton Jun 11, 2019

gillkyle Jun 11, 2019

marcysutton Jun 12, 2019

gillkyle left a comment •

edited

gillkyle Jun 11, 2019

calcsam commented Jun 11, 2019


		## Setting up Gatsby Image

		To install Gatsby Image, install the `gatsby-image` package along with necessary plugins `gatsby-transformer-sharp` and `gatsby-plugin-sharp`. Reference the packages in your Gatsby config file. You can also provide additional options to [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp/) in your config file.

	Read more in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/?=#fluid) README.
	Read more in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/#fluid) README.


		Additionally, plugins supporting `gatsby-image` currently include [gatsby-source-contentful](/packages/gatsby-source-contentful/), [gatsby-source-datocms](https://github.com/datocms/gatsby-source-datocms) and [gatsby-source-sanity](https://github.com/sanity-io/gatsby-source-sanity). See the [gatsby-image](/packages/gatsby-image/#fragments) README for more details.

		## Gatsby-image props

fix(docs): improve image docs from workflow evaluation #14697

fix(docs): improve image docs from workflow evaluation #14697

Conversation

marcysutton commented Jun 11, 2019

Description

jlengstorf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gillkyle left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

calcsam commented Jun 11, 2019

gillkyle left a comment •

edited