diff --git a/docs/docs/reference/release-notes/v2.26/index.md b/docs/docs/reference/release-notes/v2.26/index.md index 391f9dcee89bd..14ffbfbd2a52d 100644 --- a/docs/docs/reference/release-notes/v2.26/index.md +++ b/docs/docs/reference/release-notes/v2.26/index.md @@ -13,11 +13,11 @@ Key highlights of this release: - [New Image Plugin (beta)](#gatsby-plugin-image010-beta) - access static images without GraphQL, high Lighthouse scores again - [File System Route API](#file-system-route-api) - create routes from your data using filename conventions - [New Release Process](#new-release-process) - more stability and clarity around Gatsby releases -- [gatsby-source-contentful v4.0](#gatsby-source-contentful400) - new RichText implementation, performance improvements +- [`gatsby-source-contentful` v4.0](#gatsby-source-contentful400) - new RichText implementation, performance improvements Other notable changes: -- [gatsby-plugin-mdx](#gatsby-plugin-mdx140) - performance improvements +- [`gatsby-plugin-mdx`](#gatsby-plugin-mdx140) - performance improvements - [Enable compression in the dev server](#enable-compression-in-the-dev-server) - speeds up remote previews Sneak peek to next releases: @@ -53,19 +53,19 @@ and related PR [#27424](https://github.com/gatsbyjs/gatsby/pull/27424). ### Enable compression in the dev server This lowers the amount of data transferred for one site especially in remote situations. -Most of that drop was from the commons.js bundle. +Most of that drop was from the `commons.js` bundle. See PR [#27948](https://github.com/gatsbyjs/gatsby/pull/27948) for details. -## gatsby-plugin-image@0.1.0 (beta) +## `gatsby-plugin-image@0.1.0` (beta) [New image plugin](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-image) to replace `gatsby-image`, which greatly improves performance (Lighthouse 💯 again) and adds easy static images (no GraphQL). Part of it is also a new, simpler API for `gatsby-transformer-sharp`. -### StaticImage +### `StaticImage` This component is a new, simpler way to use Gatsby's image processing for static images without needing to write GraphQL queries: -```js +```jsx import React from "react" import { StaticImage } from "gatsby-plugin-image" @@ -74,7 +74,7 @@ export const Dino = () => ( ) ``` -### GatsbyImage +### `GatsbyImage` This is a complete rewrite of the Gatsby Image component, using native lazy loading whenever possible. In our tests it allows sites whose Lighthouse scores dropped in recent updates to get back to 100s across the board. @@ -108,7 +108,7 @@ export function Plant({ data }) { - [Details, Migration guide and discussion](https://github.com/gatsbyjs/gatsby/discussions/27950) - [Documentation](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-image) -## gatsby-source-contentful@4.0.0 +## `gatsby-source-contentful@4.0.0` ### New Rich Text Implementation @@ -127,7 +127,7 @@ it manually in your site config to see performance improvements. Due to technical limitations, the response payload size is still bound by a hard chunk download size, so it is possible you may need to use a lower value for your particular site. -## gatsby-plugin-mdx@1.4.0 +## `gatsby-plugin-mdx@1.4.0` There was a significant performance improvement by making a certain node fetching step lazy. This is especially noticeable at scale. See PR [#27937](https://github.com/gatsbyjs/gatsby/pull/27937) for details. @@ -142,7 +142,7 @@ This would avoid having to wait for slower queries (like image processing) if yo Try early alpha (and [let us know](https://github.com/gatsbyjs/gatsby/discussions/27620) if you have any issues with it): -``` +```shell npm install gatsby@qod ``` @@ -164,7 +164,7 @@ This experimental version of `gatsby-plugin-sharp` only does image processing wh Try early alpha (and [let us know](https://github.com/gatsbyjs/gatsby/discussions/27603) if you have any issues with it): -``` +```shell npm install gatsby-plugin-sharp@lazy-images ``` diff --git a/docs/docs/reference/release-notes/v2.27/index.md b/docs/docs/reference/release-notes/v2.27/index.md index 9ecb349468826..48b7d7a1bd5c8 100644 --- a/docs/docs/reference/release-notes/v2.27/index.md +++ b/docs/docs/reference/release-notes/v2.27/index.md @@ -11,11 +11,11 @@ Welcome to `gatsby@2.27.0` release (November 2020 #2). Key highlights of this release: -- [create-gatsby](#create-gatsby) - new, interactive way to create a Gatsby site +- [`create-gatsby`](#create-gatsby) - new, interactive way to create a Gatsby site - [Experimental: Queries on Demand](#experimental-queries-on-demand) - improves `gatsby develop` bootup time - [Experimental: Lazy page bundling](#experimental-lazy-page-bundling-in-development) - also improves `gatsby develop` bootup time - [Experimental: SSR in develop](#experimental-ssr-in-development) - catch SSR errors early -- [gatsby-plugin-mdx@1.5.0](#gatsby-plugin-mdx150) - new option for better performance +- [`gatsby-plugin-mdx@1.5.0`](#gatsby-plugin-mdx150) - new option for better performance - [Notable bugfixes](#notable-bugfixes) Sneak peek to next releases: @@ -29,7 +29,7 @@ Sneak peek to next releases: [Full changelog](https://github.com/gatsbyjs/gatsby/compare/gatsby@2.27.0-next.0...gatsby@2.27.0) -## create-gatsby +## `create-gatsby` There is now a new, interactive way to create a Gatsby site. As long as you have Node.js installed you're ready to go. @@ -75,7 +75,7 @@ Try it out immediately by running `GATSBY_EXPERIMENTAL_DEV_SSR=true gatsby devel ### Experimental: Lazy page bundling in development -UPDATE: After a number of community members tested the change on their website, we decided it wasn't going to work out—https://github.com/gatsbyjs/gatsby/discussions/28137#discussioncomment-138998 +UPDATE: After a number of community members tested the change on their website, we decided it wasn't going to work out — https://github.com/gatsbyjs/gatsby/discussions/28137#discussioncomment-138998 An obstacle to Gatsby being a delightful experience for larger sites is JavaScript compilation can start to get annoyingly slow. For example, gatsbyjs.com takes over two minutes currently (with a cold cache) to compile and bundle the code for the many page components. Not acceptable! @@ -85,7 +85,7 @@ Now when you run `GATSBY_EXPERIMENT_DEVJS_LAZY=true gatsby develop`, webpack won All sites should see some speedups but it's especially noticeable for larger sites like gatsbyjs.com which now starts webpack 81% faster than before! Please test it out and tell us how fast your dev server boots up over at the [umbrella issue](https://github.com/gatsbyjs/gatsby/discussions/28137) along with any bugs you might run across. -## gatsby-plugin-mdx@1.5.0 +## `gatsby-plugin-mdx@1.5.0` Adds a `lessBabel` option to the plugin which allows you to use a fast path for scanning exports during sourcing. The savings are significant, especially at scale, but as the new scanner does not use Babel, if your site depends on Babel then you can't use this. Please give the option a try and report any problems unrelated to not running Babel so we can improve the support. @@ -106,7 +106,7 @@ This experimental version of `gatsby-plugin-sharp` only does image processing wh Try early alpha (and [let us know](https://github.com/gatsbyjs/gatsby/discussions/27603) if you have any issues with it): -``` +```shell npm install gatsby-plugin-sharp@lazy-images ``` diff --git a/docs/docs/reference/release-notes/v2.28/index.md b/docs/docs/reference/release-notes/v2.28/index.md index e62a134c232d3..dd00bc1b194f1 100644 --- a/docs/docs/reference/release-notes/v2.28/index.md +++ b/docs/docs/reference/release-notes/v2.28/index.md @@ -12,7 +12,7 @@ Welcome to `gatsby@2.28.0` release (December 2020 #1). Key highlights of this release: - [New `gatsby new`](#new-gatsby-new) - new, interactive way to create a Gatsby site -- [Feature flags in gatsby-config](#feature-flags-in-gatsby-config) - set your feature toggles without environment variables +- [Feature flags in `gatsby-config.js`](#feature-flags-in-gatsby-configjs) - set your feature toggles without environment variables - [Improved Fast Refresh integration](#improved-fast-refresh-integration) - better hot reloading - [Experimental: Lazy images in develop](#experimental-lazy-images-in-develop) - run image transformations only when they are needed by browser @@ -20,7 +20,7 @@ Other notable changes: - [Image plugin helpers](#image-plugin-helpers) - make it easier for plugin authors to support the new gatsby image plugin - [Experimental: New cache clearing behaviors](#experimental-new-cache-clearing-behaviors) - we're experimenting with ways to be smarter about clearing caches -- [gatsby-plugin-emotion v5.0](#gatsby-plugin-emotion500) - now uses emotion v11 +- [`gatsby-plugin-emotion` v5.0](#gatsby-plugin-emotion500) - now uses emotion v11 - [Removed experimental lazy page bundling](#removed-experimental-lazy-page-bundling) - [Notable bugfixes](#notable-bugfixes) @@ -39,7 +39,7 @@ if you have any [issues](https://github.com/gatsbyjs/gatsby/issues). In previous release we added [interactive way of scaffolding new gatsby project](/docs/reference/release-notes/v2.27#create-gatsby) (with `npm init gatsby`). As of this release, `gatsby new` (without any addition arguments) will use the same flow. -## Feature flags in `gatsby-config` +## Feature flags in `gatsby-config.js` Gatsby traditionally used environment variables to use various modes or enable experimental features. This worked, but it was far from pleasant and had many issues, notably: @@ -66,7 +66,7 @@ Currently supported flags: - `QUERY_ON_DEMAND` - Only run queries when needed instead of running all queries upfront. Speeds starting the develop server. - `LAZY_IMAGES` - Don't process images during development until they're requested from the browser. Speeds starting the develop server (requires `gatsby-plugin-sharp@^2.10.0`). See [Experimental: Lazy images in develop](#experimental-lazy-images-in-develop) section for additional details. - `FAST_DEV` - Umbrella flag that enables `DEV_SSR`, `QUERY_ON_DEMAND` and `LAZY_IMAGES` features. -- `FAST_REFRESH` - Use React Fast Refresh instead of the legacy react-hot-loader for instantaneous feedback in your development server. Recommended for versions of React >= 17.0. +- `FAST_REFRESH` - Use React Fast Refresh instead of the legacy `react-hot-loader` for instantaneous feedback in your development server. Recommended for versions of React >= 17.0. ## Improved Fast Refresh integration @@ -138,7 +138,7 @@ module.exports = { } ``` -## gatsby-plugin-emotion@5.0.0 +## `gatsby-plugin-emotion@5.0.0` The plugin is updated to the new major version of emotion: v11. Check out [this post](https://emotion.sh/docs/emotion-11) in emotion docs for updates. @@ -157,7 +157,7 @@ In `gatsby@2.27.0` we added [Experimental: Lazy page bundling](/docs/reference/r Plugin APIs in Gatsby run serially. Generally this what we want as most API calls are CPU/IO bound so things are fastest letting each plugin have the full undivided attention of your computer. But source plugins are often _network_ bound as they're hitting remote APIs and waiting for responses. We tried [changing the invocation of `sourceNodes` to parallel](https://github.com/gatsbyjs/gatsby/pull/28214) on a few sites with 4+ source plugins and saw a big speedup on sourcing (40%+) as they were no longer waiting on each other to start their API calls. -This is a very "Your mileage may vary" situation — not all sites will notice any difference and also not all source plugins are network bound (gatsby-source-filesystem reads from the local machine). We're looking at finding better heuristics so that all sites are as fast as possible at data sourcing but in the meantime, if you have sites with multiple source plugins, this could be a big help. +This is a very "Your mileage may vary" situation — not all sites will notice any difference and also not all source plugins are network bound (`gatsby-source-filesystem` reads from the local machine). We're looking at finding better heuristics so that all sites are as fast as possible at data sourcing but in the meantime, if you have sites with multiple source plugins, this could be a big help. You can try it today using `gatsby@next` version and adding a flag to your `gatsby-config.js`: diff --git a/docs/docs/reference/release-notes/v2.29/index.md b/docs/docs/reference/release-notes/v2.29/index.md index 4822af447f5f8..1b55c903e73c4 100644 --- a/docs/docs/reference/release-notes/v2.29/index.md +++ b/docs/docs/reference/release-notes/v2.29/index.md @@ -20,7 +20,7 @@ Other notable changes: - [Performance improvements](#performance-improvements) - [Slugify option for File System Route API](#slugify-option-for-file-system-route-api) -- [gatsby-image codemod](#gatsby-image-codemod) +- [`gatsby-image` codemod](#gatsby-image-codemod) - [Notable bugfixes](#notable-bugfixes) **Bleeding Edge:** Want to try new features as soon as possible? Install `gatsby@next` and let us know @@ -131,7 +131,7 @@ We were able to ship a bunch of performance improvements both to Gatsby itself a The File System Route API uses [slugify](https://github.com/sindresorhus/slugify) to create slugs for the generated routes. You're now able to pass custom options to that instance, e.g. when you want to change the separator. The full details are listed in the [README](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-page-creator) of `gatsby-plugin-page-creator`. -## gatsby-image codemod +## `gatsby-image` codemod We introduced some API changes for working with images when we published the new `gatsby-plugin-image` in [v2.26](/docs/reference/release-notes/v2.26#gatsby-plugin-image010-beta). In order to make it easier to migrate your code to work with the new plugin, we've created a codemod. Follow the migration instructions in the [README](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-image#upgrading-from-the-gatsby-image2) in order to run the codemod against your project. diff --git a/docs/docs/reference/release-notes/v2.30/index.md b/docs/docs/reference/release-notes/v2.30/index.md index d8fca9ccf933f..1cba55920f226 100644 --- a/docs/docs/reference/release-notes/v2.30/index.md +++ b/docs/docs/reference/release-notes/v2.30/index.md @@ -13,7 +13,7 @@ Key highlights of this release: - [Query on Demand and Lazy Images: Generally available](#query-on-demand-and-lazy-images-generally-available) - improves `gatsby develop` bootup time - [Server Side Rendering (SSR) in development](#server-side-rendering-ssr-in-development) — helps you find and fix many build errors in development. We're starting a partial release of this feature to 5% of users. -- [gatsby-plugin-sass v3](#gatsby-plugin-sass300) - use the latest `sass-loader` and `Dart Sass` by default +- [`gatsby-plugin-sass` v3](#gatsby-plugin-sass300) - use the latest `sass-loader` and `Dart Sass` by default - [Image transformations up to 30% faster](#gatsby-plugin-sharp2120) And several impactful updates in the new [`gatsby-plugin-image`](#gatsby-plugin-image050-beta) (beta): @@ -76,7 +76,7 @@ module.exports = { } ``` -## gatsby-plugin-sass@3.0.0 +## `gatsby-plugin-sass@3.0.0` Now that [LibSass and Node Sass are deprecated](https://sass-lang.com/blog/libsass-is-deprecated), we've upgraded `sass-loader` to `10.1.0` and thus switched sass implementation to [Dart Sass](https://sass-lang.com/dart-sass). @@ -92,7 +92,7 @@ See also: - https://github.com/gatsbyjs/gatsby/issues/27754 - https://github.com/gatsbyjs/gatsby/pull/27991 -## gatsby-plugin-sharp@2.12.0 +## `gatsby-plugin-sharp@2.12.0` New approach to concurrency speeds up image transformations up to 30%. @@ -102,7 +102,7 @@ to each image serially. Another major change is [lazy images in develop](#query-on-demand-and-lazy-images-generally-available). -## gatsby-plugin-image@0.5.0 (beta) +## `gatsby-plugin-image@0.5.0 (beta)` ### AVIF support @@ -154,7 +154,7 @@ GATSBY_EXPERIMENTAL_REMOTE_IMAGES=1 gatsby build You can then pass absolute URLs to `StaticImage`: -```js +```jsx ```