From 2bd523ad05d3484a6589e0146bd8d55c4381e57e Mon Sep 17 00:00:00 2001 From: Josh Johnson Date: Wed, 23 Nov 2022 08:54:36 -0500 Subject: [PATCH] chore(docs): Remove tracedSVG option from docs (#37090) Remove tracedSVG option from docs --- docs/docs/conceptual/image-plugin-architecture.md | 4 ++-- docs/docs/conceptual/using-gatsby-image.md | 2 +- .../images-and-media/using-gatsby-plugin-image.md | 1 - .../adding-gatsby-image-support.md | 4 ++-- .../reference/built-in-components/gatsby-image.md | 10 +--------- .../built-in-components/gatsby-plugin-image.md | 13 +++++-------- .../release-notes/image-migration-guide.md | 2 +- .../release-notes/migrating-from-v1-to-v2.md | 4 ++-- .../release-notes/migrating-from-v2-to-v3.md | 4 ++-- docs/tutorial/wordpress-image-tutorial.md | 8 +++----- 10 files changed, 19 insertions(+), 33 deletions(-) diff --git a/docs/docs/conceptual/image-plugin-architecture.md b/docs/docs/conceptual/image-plugin-architecture.md index 159e436259988..80114fa595290 100644 --- a/docs/docs/conceptual/image-plugin-architecture.md +++ b/docs/docs/conceptual/image-plugin-architecture.md @@ -30,7 +30,7 @@ The plugin exports a number of other helper functions designed to help end-users ### `gatsby-plugin-sharp` -This includes the actual image processing functions from sharp and potrace. It includes the functions that generate the image data object, including calculating which srcset sizes to generate. It exports `generateImageData`, which is used by `gatsby-transformer-sharp` and `gatsby-plugin-image`. It takes a `File` node and the image processing arguments, calculates which images to generate, processes these images and returns an image data object suitable for passing to `GatsbyImage`. It also exports helper functions for third party plugins to use, such as `traceSVG`. +This includes the actual image processing functions from sharp. It includes the functions that generate the image data object, including calculating which srcset sizes to generate. It exports `generateImageData`, which is used by `gatsby-transformer-sharp` and `gatsby-plugin-image`. It takes a `File` node and the image processing arguments, calculates which images to generate, processes these images and returns an image data object suitable for passing to `GatsbyImage`. It also exports helper functions for third party plugins to use, such as `generateImageData`. ### `gatsby-transformer-sharp` @@ -62,7 +62,7 @@ The `GatsbyImage` component supports three types of layout, which define the res #### Placeholder -`GatsbyImage` supports displaying a placeholder while the main image loads. There are two kinds of placeholder that are currently supported: flat colors and images. The type of placeholder is set via the image data object, and will either be a data URI for the image, or a CSS color value. The image will either be a base64-encoded low resolution raster image (called `BLURRED` when using sharp) or a URI-encoded SVG (called `TRACED_SVG`). The raster image will by default be 20px wide, and the same aspect ratio as the main image. This will be resized to fill the full container, giving a blurred effect. The SVG image is expected to be a single-color, simplified SVG generated using [potrace](http://potrace.sourceforge.net/). While these are the defaults produced by sharp, and also used by many third-party source plugins, we do not enforce this, and it can be any URI. We strongly encourage the use of inline data URIs, as any placeholder that needs to make a network request will defeat much of the purpose of using a placeholder. The actual placeholder element is a regular `` tag, even for SVGs. +`GatsbyImage` supports displaying a placeholder while the main image loads. There are two kinds of placeholder that are currently supported: flat colors and images. The type of placeholder is set via the image data object, and will either be a data URI for the image, or a CSS color value. The image will be a base64-encoded low resolution raster image (called `BLURRED` when using sharp). The raster image will by default be 20px wide, and the same aspect ratio as the main image. This will be resized to fill the full container, giving a blurred effect. While these are the defaults produced by sharp, and also used by many third-party source plugins, we do not enforce this, and it can be any URI. We strongly encourage the use of inline data URIs, as any placeholder that needs to make a network request will defeat much of the purpose of using a placeholder. The actual placeholder element is a regular `` tag, even for SVGs. The alternative placeholder is a flat color. This is expected to be calculated from the dominant color of the source image. sharp supports performing this calculation, and some CMSs provide it in the image metadata. This color is applied as a background color to a placeholder `
` element. diff --git a/docs/docs/conceptual/using-gatsby-image.md b/docs/docs/conceptual/using-gatsby-image.md index 9a2fa05703a24..78b863fc7ef8a 100644 --- a/docs/docs/conceptual/using-gatsby-image.md +++ b/docs/docs/conceptual/using-gatsby-image.md @@ -52,7 +52,7 @@ When a browser doesn't know how big an image is going to be, either because the In addition, when an image appears, it goes from blank background to fully there from one frame to another. This can also be visually jarring. Like CSS has a `transition` prop to help position shifts feel gradual, images feel more aesthetically pleasing when they have placeholders. -Gatsby Image's will hold the spot for your image automatically when you specify `width` prop, and depending on your preference, will provide a background -- blurred, a background color, or traced SVG, while the image loads. +Gatsby Image's will hold the spot for your image automatically when you specify `width` prop, and depending on your preference, will provide a background -- blurred or a background color, while the image loads. ![Gatsby Image Gradual Transition](../images/gatsby-image-gif.gif) diff --git a/docs/docs/how-to/images-and-media/using-gatsby-plugin-image.md b/docs/docs/how-to/images-and-media/using-gatsby-plugin-image.md index 9281842cd9b38..991525ee3bf95 100644 --- a/docs/docs/how-to/images-and-media/using-gatsby-plugin-image.md +++ b/docs/docs/how-to/images-and-media/using-gatsby-plugin-image.md @@ -212,7 +212,6 @@ module.exports = { quality: 50, breakpoints: [750, 1080, 1366, 1920], backgroundColor: `transparent`, - tracedSVGOptions: {}, blurredOptions: {}, jpgOptions: {}, pngOptions: {}, diff --git a/docs/docs/how-to/plugins-and-themes/adding-gatsby-image-support.md b/docs/docs/how-to/plugins-and-themes/adding-gatsby-image-support.md index cc82f799d1fb9..a632fece6f084 100644 --- a/docs/docs/how-to/plugins-and-themes/adding-gatsby-image-support.md +++ b/docs/docs/how-to/plugins-and-themes/adding-gatsby-image-support.md @@ -7,7 +7,7 @@ Support for these are available out of the box in `gatsby-transformer-sharp`, so ## Adding a `gatsbyImageData` GraphQL resolver -You can give your users the best experience by adding a `gatsbyImageData` resolver to your image nodes. This allows you to generate low-resolution or traced SVG images as inline data URIs to use as placeholders. You can also calculate the image's dominant color for an alternative placeholder. These are the same placeholders that are included with `gatsby-transformer-sharp`, and will give the best experience for your users. If you are able to deliver these directly from your CMS or other data source then this is ideal, but otherwise you can use helper functions included in `gatsby-plugin-sharp`. +You can give your users the best experience by adding a `gatsbyImageData` resolver to your image nodes. This allows you to generate low-resolution images as inline data URIs to use as placeholders. You can also calculate the image's dominant color for an alternative placeholder. These are the same placeholders that are included with `gatsby-transformer-sharp`, and will give the best experience for your users. If you are able to deliver these directly from your CMS or other data source then this is ideal, but otherwise you can use helper functions included in `gatsby-plugin-sharp`. There are three steps to add a basic `gatsbyImageData` resolver: @@ -72,7 +72,7 @@ const resolveGatsbyImageData = async (image, options) => { } // You could also calculate dominant color, and pass that as `backgroundColor` - // gatsby-plugin-sharp includes helpers that you can use to generate a tracedSVG or calculate + // gatsby-plugin-sharp includes helpers that you can use, such as calculating // the dominant color of a local file, if you don't want to handle it in your plugin diff --git a/docs/docs/reference/built-in-components/gatsby-image.md b/docs/docs/reference/built-in-components/gatsby-image.md index efc9c9f24ef1c..6e1a641620423 100644 --- a/docs/docs/reference/built-in-components/gatsby-image.md +++ b/docs/docs/reference/built-in-components/gatsby-image.md @@ -294,28 +294,20 @@ GraphQL includes a concept called "query fragments", which are a part of a query - `GatsbyImageSharpFixed` - `GatsbyImageSharpFixed_noBase64` -- `GatsbyImageSharpFixed_tracedSVG` - `GatsbyImageSharpFixed_withWebp` - `GatsbyImageSharpFixed_withWebp_noBase64` -- `GatsbyImageSharpFixed_withWebp_tracedSVG` #### Fluid images - `GatsbyImageSharpFluid` - `GatsbyImageSharpFluid_noBase64` -- `GatsbyImageSharpFluid_tracedSVG` - `GatsbyImageSharpFluid_withWebp` - `GatsbyImageSharpFluid_withWebp_noBase64` -- `GatsbyImageSharpFluid_withWebp_tracedSVG` #### About `noBase64` If you don't want to use the [blur-up effect](https://using-gatsby-image.gatsbyjs.org/blur-up/), choose the fragment with `noBase64` at the end. -#### About `tracedSVG` - -If you want to use the [traced placeholder SVGs](https://using-gatsby-image.gatsbyjs.org/traced-svg/), choose the fragment with `tracedSVG` at the end. - #### About `withWebp` If you want to automatically use [WebP images](https://developers.google.com/speed/webp/) when the browser supports the file format, use the `withWebp` fragments. If the browser doesn't support WebP, `gatsby-image` will fall back to the default image format. @@ -327,7 +319,7 @@ file(relativePath: { eq: "images/default.jpg" }) { childImageSharp { fluid { // highlight-next-line - ...GatsbyImageSharpFluid_tracedSVG + ...GatsbyImageSharpFluid } } } diff --git a/docs/docs/reference/built-in-components/gatsby-plugin-image.md b/docs/docs/reference/built-in-components/gatsby-plugin-image.md index a7270605815c9..2136c4a1468a1 100644 --- a/docs/docs/reference/built-in-components/gatsby-plugin-image.md +++ b/docs/docs/reference/built-in-components/gatsby-plugin-image.md @@ -232,12 +232,11 @@ For `fullWidth` images you don't specify width or height, as it resizes to fit t Gatsby image components are lazy-loaded by default, which means that if they are offscreen they are not loaded by the browser until they come into view. To ensure that the layout does not jump around, a placeholder is displayed before the image loads. You can choose one of three types of placeholder (or not use a placeholder at all): -| Placeholder | Component prop value | Resolver prop value | Description | -| -------------- | -------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Dominant color | `"dominantColor"` | `DOMINANT_COLOR` | The default placeholder. This calculates the dominant color of the source image and uses it as a solid background color. | -| Blurred | `"blurred"` | `BLURRED` | This generates a very low-resolution version of the source image and displays it as a blurred background. | -| Traced SVG | `"tracedSVG"` | `TRACED_SVG` | This generates a simplified, flat SVG version of the source image, which it displays as a placeholder. This works well for images with simple shapes or that include transparency. | -| None | `"none"` | `NONE` | No placeholder. You can use the background color option to set a static background if you wish. | +| Placeholder | Component prop value | Resolver prop value | Description | +| -------------- | -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| Dominant color | `"dominantColor"` | `DOMINANT_COLOR` | The default placeholder. This calculates the dominant color of the source image and uses it as a solid background color. | +| Blurred | `"blurred"` | `BLURRED` | This generates a very low-resolution version of the source image and displays it as a blurred background. | +| None | `"none"` | `NONE` | No placeholder. You can use the background color option to set a static background if you wish. | ### `formats` @@ -275,7 +274,6 @@ The Gatsby Image plugin uses [sharp](https://sharp.pixelplumbing.com) for image | `outputPixelDensities` | For fixed images: `[1, 2]`
For constrained: `[0.25, 0.5, 1, 2]` | A list of image pixel densities to generate. It will never generate images larger than the source, and will always include a 1x image. The value is multiplied by the image width, to give the generated sizes. For example, a `400` px wide constrained image would generate `100`, `200`, `400` and `800` px wide images by default. Ignored for full width layout images, which use `breakpoints` instead. | | `breakpoints` | `[750, 1080, 1366, 1920]` | Output widths to generate for full width images. Default is to generate widths for common device resolutions. It will never generate an image larger than the source image. The browser will automatically choose the most appropriate. | | `blurredOptions` | None | Options for the low-resolution placeholder image. Ignored unless [`placeholder`](#placeholder) is blurred. | -| `tracedSVGOptions` | None | Options for traced placeholder SVGs. See [potrace options](https://www.npmjs.com/package/potrace#parameters). Ignored unless [`placeholder`](#placeholder) is traced SVG. | | `jpgOptions` | None | Options to pass to sharp when generating JPG images. | | `pngOptions` | None | Options to pass to sharp when generating PNG images. | | `webpOptions` | None | Options to pass to sharp when generating WebP images. | @@ -300,7 +298,6 @@ module.exports = { quality: 50, breakpoints: [750, 1080, 1366, 1920], backgroundColor: `transparent`, - tracedSVGOptions: {}, blurredOptions: {}, jpgOptions: {}, pngOptions: {}, diff --git a/docs/docs/reference/release-notes/image-migration-guide.md b/docs/docs/reference/release-notes/image-migration-guide.md index e5c544c7c0a33..afad1c9f55c09 100644 --- a/docs/docs/reference/release-notes/image-migration-guide.md +++ b/docs/docs/reference/release-notes/image-migration-guide.md @@ -110,7 +110,7 @@ Previously, images generated their own type by default, e.g. JPG, PNG, etc. You Previously, transformations like `grayscale` and quality options such as `pngQuality` were top level query arguments. This has changed. -`grayscale` now exists within the `transformOptions` argument, and `pngQuality` becomes `quality` inside `pngOptions`. The `traceSVG` object is now `tracedSVGOptions`. See the [`gatsby-plugin-image` Reference Guide](/docs/reference/built-in-components/gatsby-plugin-image) for specifics. +`grayscale` now exists within the `transformOptions` argument, and `pngQuality` becomes `quality` inside `pngOptions`. See the [`gatsby-plugin-image` Reference Guide](/docs/reference/built-in-components/gatsby-plugin-image) for specifics. ### Breaking changes diff --git a/docs/docs/reference/release-notes/migrating-from-v1-to-v2.md b/docs/docs/reference/release-notes/migrating-from-v1-to-v2.md index eab564e6fc6f1..ece51bd5cadcb 100644 --- a/docs/docs/reference/release-notes/migrating-from-v1-to-v2.md +++ b/docs/docs/reference/release-notes/migrating-from-v1-to-v2.md @@ -875,9 +875,9 @@ export const pageQuery = graphql` foo: file(relativePath: { regex: "/foo.jpg/" }) { childImageSharp { - sizes(maxWidth: 700) { -- ...GatsbyImageSharpSizes_tracedSVG +- ...GatsbyImageSharpSizes + fluid(maxWidth: 700) { -+ ...GatsbyImageSharpFluid_tracedSVG ++ ...GatsbyImageSharpFluid } } } diff --git a/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md b/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md index 92a44db1861b3..aaaa92dc3e7ae 100644 --- a/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md +++ b/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md @@ -274,9 +274,9 @@ export const pageQuery = graphql` foo: file(relativePath: { regex: "/foo.jpg/" }) { childImageSharp { - sizes(maxWidth: 700) { -- ...GatsbyImageSharpSizes_tracedSVG +- ...GatsbyImageSharpSizes + fluid(maxWidth: 700) { -+ ...GatsbyImageSharpFluid_tracedSVG ++ ...GatsbyImageSharpFluid } } } diff --git a/docs/tutorial/wordpress-image-tutorial.md b/docs/tutorial/wordpress-image-tutorial.md index 08b393760db3d..0a8dce99187b2 100644 --- a/docs/tutorial/wordpress-image-tutorial.md +++ b/docs/tutorial/wordpress-image-tutorial.md @@ -16,7 +16,7 @@ In this tutorial, you will install the several image plugins and components in o Images are one of the most beautiful and striking ways to communicate to people, and are a key part of creating an effective and positive user experience; at the same time, high quality images can load slowly and cause text boxes to jump around, both of which make it difficult for people to be patient with visiting your website. -The Gatsby Way™ of creating images describes a set of best practices that help you optimize performance and responsiveness of images so that you can get the benefits of awesome images that don't slow down your site. This [Gatsbygram site](https://gatsbygram.gatsbyjs.org/) (an Instagram feed fed through Gatsby) shows off the SVG image tracing effect. Here’s an [image processing demo site](https://image-processing.gatsbyjs.org/) exploring how to have fun with images in your Gatsby site. +The Gatsby Way™ of creating images describes a set of best practices that help you optimize performance and responsiveness of images so that you can get the benefits of awesome images that don't slow down your site. ## Installing the `gatsby-source-wordpress` plugin @@ -201,8 +201,6 @@ Here’s an example query for generating different sizes of an image: } ``` -In either case, you can add traced SVG support by adding `_tracedSVG` to the end of each fragment. _Note this won’t work in the GraphQL explorer._ - ## Rendering the images to `index.js` Here is what your `index.js` should look like with the query added: @@ -243,7 +241,7 @@ export const query = graphql` childImageSharp { # edit the maxWidth value to generate resized images fixed(width: 500, height: 500) { - ...GatsbyImageSharpFixed_withWebp_tracedSVG + ...GatsbyImageSharpFixed_withWebp } } } @@ -264,7 +262,7 @@ Your demo site should look something like this: It is useful and can be fun to purposefully slow down your browser to see image effects animate more slowly. -Open your browser console and change the network speed to something slower. In Chrome, you can click on the “network” tab, then on the drop down arrow next to the word “Online.” Then click “Slow 3G.” Now, reload your page and watch the blur-up and SVG effects in action. The network tab also shows statistics on when each image loaded and how much time it took them to load. +Open your browser console and change the network speed to something slower. In Chrome, you can click on the “network” tab, then on the drop down arrow next to the word “Online.” Then click “Slow 3G.” Now, reload your page and watch the blur-up effect in action. The network tab also shows statistics on when each image loaded and how much time it took them to load. ![Network](./images/network.png)