diff --git a/docs/docs/how-to/previews-deploys-hosting/adapters.md b/docs/docs/how-to/previews-deploys-hosting/adapters.md
new file mode 100644
index 0000000000000..20bd9449f3138
--- /dev/null
+++ b/docs/docs/how-to/previews-deploys-hosting/adapters.md
@@ -0,0 +1,58 @@
+---
+title: Adapters
+---
+
+## Introduction
+
+Adapters are responsible for taking the production output from Gatsby and turning it into something your deployment platform understands. They make it easier to build and deploy Gatsby sites on any deployment platform.
+
+Gatsby has different [rendering options](/docs/conceptual/rendering-options/) and features like Deferred Static Generation (DSG) and Server-Side rendering (SSR) require more setup than classic static site generation (SSG). Users can also set [HTTP headers](/docs/how-to/previews-deploys-hosting/headers/) or create [redirects](/docs/reference/config-files/actions/#createRedirect).
+
+Gatsby passes all the required information during the build to adapters to prepare these outputs for deployment on a specific platform. Here are some of the actions an adapter automatically takes:
+
+- Applies HTTP headers to assets
+- Applies redirects and rewrites. The adapter can also create its own redirects or rewrites if necessary, for example to map serverless functions to internal URLs.
+- Wraps serverless functions coming from Gatsby with platform-specific code (if necessary). Gatsby will produce [Express](https://expressjs.com/)-like handlers.
+- Apply trailing slash behavior and path prefix to URLs
+- Possibly uploads assets to CDN
+
+This feature was added in `gatsby@5.12.0`.
+
+## Finding adapters
+
+You can use these official adapters:
+
+- [gatsby-adapter-netlify](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-adapter-netlify) for [Netlify](https://www.netlify.com/)
+
+To find additional community adapters, [search npm for `gatsby-adapter`](https://www.npmjs.com/search?q=gatsby-adapter-).
+
+Can't find an adapter for your platform? Consider [creating an adapter](/docs/how-to/previews-deploys-hosting/creating-an-adapter/) yourself.
+
+## Using adapters
+
+Use the `adapter` option inside `gatsby-config`:
+
+```js:title=gatsby-config.js
+const adapter = require("gatsby-adapter-foo")
+
+module.exports = {
+ adapter: adapter()
+}
+```
+
+If the adapter accepts custom options, you can set them like this:
+
+```js:title=gatsby-config.js
+const adapter = require("gatsby-adapter-foo")
+
+module.exports = {
+ adapter: adapter({
+ // Adapter options
+ })
+}
+```
+
+## Additional resources
+
+- [Zero-Configuration Deployments](/docs/how-to/previews-deploys-hosting/zero-configuration-deployments/)
+- [Creating an Adapter](/docs/how-to/previews-deploys-hosting/creating-an-adapter/)
diff --git a/docs/docs/how-to/previews-deploys-hosting/caching.md b/docs/docs/how-to/previews-deploys-hosting/caching.md
index 3b56dba6f6041..cdc3a8f9f412a 100644
--- a/docs/docs/how-to/previews-deploys-hosting/caching.md
+++ b/docs/docs/how-to/previews-deploys-hosting/caching.md
@@ -4,7 +4,7 @@ title: Caching Static Sites
An important part of creating a very fast website is setting up proper HTTP caching. HTTP caching allows browsers to cache resources from a website so that when the user returns to a site, very few parts of the website have to be downloaded.
-Different types of resources are cached differently. Let's examine how the different types of files built to `public/` should be cached.
+Different types of resources are cached differently. Let's examine how the different types of files built to `public` should be cached.
## HTML
@@ -38,7 +38,7 @@ cache-control: public, max-age=0, must-revalidate
## Static files
-All files in `static/` should be cached forever. For files in this directory, Gatsby creates paths that are directly tied to the content of the file. Meaning that if the file content changes, then the file path changes also. These paths look weird e.g. `some-name-e097c4319d0f8cff6-0b1ba.png` but since the same file will always be returned when that path is requested, Gatsby can cache it forever.
+All files in `static` should be cached forever. For files in this directory, Gatsby creates paths that are directly tied to the content of the file. Meaning that if the file content changes, then the file path changes also. These paths look weird e.g. `some-name-e097c4319d0f8cff6-0b1ba.png` but since the same file will always be returned when that path is requested, Gatsby can cache it forever.
The `cache-control` header should be:
@@ -48,7 +48,7 @@ cache-control: public, max-age=31536000, immutable
## JavaScript and CSS
-JavaScript and CSS files _generated by webpack_ should also be cached forever. Like static files, Gatsby creates JS & CSS file names (as a hash!) based on the file content. If the file content is changed, the file hash will change, therefore these files _generated by webpack_ are safe to cache.
+JavaScript and CSS files _generated by webpack_ should also be cached forever. Like static files, Gatsby creates JS & CSS file names (as a hash) based on the file content. If the file content is changed, the file hash will change, therefore these files _generated by webpack_ are safe to cache.
The `cache-control` header should be:
@@ -62,13 +62,14 @@ The only exception to this is the file `/sw.js`, which needs to be revalidated u
cache-control: public, max-age=0, must-revalidate
```
-## Setting up caching on different hosts
+## Setting up caching on different deployment platforms
-How you set up your caching depends on how you host your site. We encourage people to create Gatsby plugins per host to automate the creation of caching headers.
+How you set up your caching depends on how you host your site. We encourage you to use a [Gatsby adapter](/docs/how-to/previews-deploys-hosting/adapters/) for your deployment platform (if available) to automate the creation and application of the caching headers mentioned above.
-The following plugins have this functionality:
+If an adapter doesn’t exist for your deployment platform yet, consider [creating an adapter](/docs/how-to/previews-deploys-hosting/creating-an-adapter/).
+
+Since Gatsby adapters were introduced in later Gatsby releases, you could also look out for plugins like:
-- [gatsby-plugin-netlify](/plugins/gatsby-plugin-netlify/)
- [gatsby-plugin-s3](/plugins/gatsby-plugin-s3/)
- [gatsby-plugin-fastify](/plugins/gatsby-plugin-fastify/)
diff --git a/docs/docs/how-to/previews-deploys-hosting/creating-an-adapter.md b/docs/docs/how-to/previews-deploys-hosting/creating-an-adapter.md
new file mode 100644
index 0000000000000..757dd8741f5ac
--- /dev/null
+++ b/docs/docs/how-to/previews-deploys-hosting/creating-an-adapter.md
@@ -0,0 +1,313 @@
+---
+title: Creating an Adapter
+examples:
+ - label: gatsby-adapter-netlify
+ href: "https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-adapter-netlify"
+---
+
+import Collapsible from "@components/collapsible"
+
+## Introduction
+
+If an [adapter](/docs/how-to/previews-deploys-hosting/adapters/) for your preferred deployment platform doesn't exist yet, you can build your own. While the specifics of the adapter depend on the deployment platform and its requirements, the initial setup is the same for every adapter.
+
+By the end of this guide you should be able to create and publish an adapter.
+
+The adapters feature was added in `gatsby@5.12.0`.
+
+## Authoring
+
+An adapter's entry point should have the following API:
+
+```js
+/**
+ * @type {import("gatsby").AdapterInit}
+ */
+const createAdapterFoo = adapterOptions => {
+ return {
+ name: `gatsby-adapter-foo`,
+ cache: {
+ restore({ directories, reporter }) {
+ // Cache restore implementation
+ },
+ store({ directories, reporter }) {
+ // Cache store implementation
+ },
+ },
+ adapt({
+ routesManifest,
+ functionsManifest,
+ pathPrefix,
+ trailingSlash,
+ reporter,
+ }) {
+ // Adapt implementation
+ },
+ config({ reporter }) {
+ return {
+ // Information passed back to Gatsby
+ }
+ },
+ }
+}
+
+module.exports = createAdapterFoo
+```
+
+TypeScript version}
+>
+
+Gatsby makes a `AdapterInit` type available that you can use to author your adapter. It also accepts a generic for the adapter options:
+
+```ts
+import type { AdapterInit } from "gatsby"
+
+type AdapterOptions = {
+ foo: boolean
+}
+
+const createAdapterFoo: AdapterInit = ({ foo }) => {
+ return {
+ name: `gatsby-adapter-foo`,
+ cache: {
+ restore({ directories, reporter }) {
+ // Cache restore implementation
+ },
+ store({ directories, reporter }) {
+ // Cache store implementation
+ },
+ },
+ adapt({
+ routesManifest,
+ functionsManifest,
+ pathPrefix,
+ trailingSlash,
+ reporter,
+ }) {
+ // Adapt implementation
+ },
+ config({ reporter }) {
+ return {
+ // Information passed back to Gatsby
+ }
+ },
+ }
+}
+
+export default createAdapterFoo
+```
+
+You can find all TypeScript types [on GitHub](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/adapter/types.ts).
+
+
+
+The adapter should export a function as a default export with these object keys:
+
+- `name`: Unique name of the adapter. Please follow the naming convention `gatsby-adapter-` or `@scope/gatsby-adapter-` to make it easier for people to discover your adapter.
+- `cache` (Optional): Both handlers receive `directories` which are the directories that should be cached/restored for a build and the [`reporter` instance](/docs/reference/config-files/node-api-helpers/#reporter).
+ - `restore`: Hook to restore `directories` from previous builds. Executed very early on in the build process. If the hook returns `false`, Gatsby will skip cache restoration.
+ - `store`: Hook to store `directories` for the current build. Executed as one of the last steps in the build process.
+- [`adapt`](#adapt): Hook to take Gatsby's output and prepare it for deployment on the adapter's platform. Executed as one of the last steps in the build process. Details on the inputs are [documented below](#adapt).
+- [`config`](#config) (Optional): Hook to pass information from the adapter to Gatsby so it can adjust its build process. Details on the required output is [documented below](#adapt).
+
+If your adapter accepts custom options, consider setting default values to make the adapter easier to use.
+
+`cache.restore`, `cache.store`, and `adapt` receive the [`reporter` instance](/docs/reference/config-files/node-api-helpers/#reporter), so you can output structured logs to the user’s terminal. **However**, please don’t overdo it and keep the output to a minimum. If a user requires more details, they can always use the CLI with the `--verbose` flag to get information about the adapter and logs for debugging.
+
+### adapt
+
+The `adapt` hook takes Gatsby's output and prepares it for deployment on the adapter's platform. It receives the following inputs:
+
+- `routesManifest`: Array of objects with three different types: `static`, `function`, and `redirect`. Each object contains all necessary information to deploy and apply these routes. `static` routes will have default `headers` applied, which users can extend or overwrite with the [HTTP headers](/docs/how-to/previews-deploys-hosting/headers/) option inside `gatsby-config`. Routes will also have the [`trailingSlash`](/docs/reference/config-files/gatsby-config/#trailingslash) option applied to their paths.
+- `functionsManifest`: Array of objects containing each function's entry point and required files.
+- `pathPrefix`: Value of the [`pathPrefix`](/docs/reference/config-files/gatsby-config/#pathprefix) option inside `gatsby-config`
+- `trailingSlash`: Value of the [`trailingSlash`](/docs/reference/config-files/gatsby-config/#trailingslash) option inside `gatsby-config`
+
+You can find the TypeScript types for these inputs on [on GitHub](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/adapter/types.ts).
+
+The `adapt` hook should do the following things:
+
+- Apply HTTP headers to assets
+- Apply redirects and rewrites. The adapter can also create its own redirects and rewrites, if necessary (e.g. mapping serverless functions to internal URLs).
+- Wrap serverless functions coming from Gatsby with platform-specific code (if necessary). Gatsby will produce [Express](https://expressjs.com/)-like handlers.
+- Apply trailing slash behavior and path prefix to URLs
+- Possibly upload assets to CDN
+
+### config
+
+The `config` hook is useful for passing information from an adapter back to Gatsby. This optional hook can enable advanced features of adapters to e.g. workaround platform limitations. It can also warn users against using features that an adapter doesn's currently support and would cause faulty deployments.
+
+The `config` hook has to return an object with the following keys:
+
+- `deployURL` (Optional): URL representing the unique URL for an individual deploy
+- `excludeDatastoreFromEngineFunction` (Optional): If `true`, Gatsby will not include the LMDB datastore in the serverless functions used for SSR/DSG. Instead, it will place the LMDB datastore into the `public` folder and later try to download the datastore from the given `deployURL`.
+- `supports` (Optional): Describe which features an adapters supports
+ - `pathPrefix` (Optional): If `false`, Gatsby will fail the build if user tries to use pathPrefix
+ - `trailingSlash` (Optional): Provide an array of supported [`trailingSlash`](/docs/reference/config-files/gatsby-config/#trailingslash) options, e.g. `['always']`
+- `pluginsToDisable` (Optional): Provide an array of plugin names that should be disabled when adapter is used. Purpose of this is to disable any potential plugins that serve similar role as adapter that would cause conflicts when both plugin and adapter is used at the same time.
+
+## Running locally
+
+If you want to test your adapter locally, you can use [npm link](https://docs.npmjs.com/cli/v9/commands/npm-link), [yarn link](https://yarnpkg.com/cli/link), or equivalent in other package managers. You'd use your adapter like so:
+
+```js:title=gatsby-config.js
+// gatsby-adapter-foo would be your linked adapter
+const adapter = require("gatsby-adapter-foo")
+
+module.exports = {
+ adapter: adapter()
+}
+```
+
+If you want to quickly prototype an adapter, you can also author your file(s) directly in an example project (before moving them to their own repository). Here's how:
+
+1. Create an adapter file called `gatsby-adapter-foo.js` at the root of your project:
+
+ ```js:title=gatsby-adapter-foo.js
+ const createAdapterFoo = adapterOptions => {
+ return {
+ name: `gatsby-adapter-foo`,
+ // cache hooks...
+ adapt({
+ routesManifest,
+ functionsManifest,
+ pathPrefix,
+ trailingSlash,
+ reporter
+ }) {
+ // Adapt implementation
+ reporter.info('gatsby-adapter-foo is working')
+ },
+ }
+ }
+
+ module.exports = createAdapterFoo
+ ```
+
+1. Import the adapter file into your `gatsby-config`:
+
+ ```js:title=gatsby-config.js
+ const adapter = require("./gatsby-adapter-foo")
+
+ module.exports = {
+ adapter: adapter()
+ }
+ ```
+
+1. Once it works, don't forget to [publish](#publishing) your adapter so that the community can benefit from it.
+
+## Testing
+
+You should test your adapter code to improve code quality and reliablity. We recommend using [Jest](https://jestjs.io/) or [Vitest](https://vitest.dev/) for unit testing and [Cypress](https://www.cypress.io/) or [Playwright](https://playwright.dev/) for end-to-end testing.
+
+You can copy Gatsby's complete [adapter end-to-end testing suite](https://github.com/gatsbyjs/gatsby/tree/master/e2e-tests/adapters) and use it for your own adapter.
+
+## Publishing
+
+You'll need to publish your adapter to [npm](https://www.npmjs.com/) so that others can use it. If this is your first time publishing to npm, consider following their [guides](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry).
+
+Before you publish, keep in mind that once people start using your adapter, you'll need to make changes responsibly (following [semver](https://docs.npmjs.com/about-semantic-versioning)) and potentially automate some of the maintenance work.
+
+We recommend that you follow this checklist before you publish your adapter for the first time:
+
+- Choose a clear name for your adapter following this naming convention:
+
+ ```
+ gatsby-adapter-
+ ```
+
+ To publish the adapter under a [scope](https://docs.npmjs.com/about-scopes), follow this naming convention:
+
+ ```
+ @scope/gatsby-adapter-
+ ```
+
+- Your `README` should explain to the user in concise steps how to install, use, and configure your adapter (also see [How to write a plugin README](/contributing/docs-contributions/how-to-write-a-plugin-readme/)). The `README` will be the first thing a user reviews so make sure that it's accessible to everyone.
+- Set `1.0.0` as the `version` field in your adapter's `package.json`. For future releases, follow [semantic versioning](https://docs.npmjs.com/about-semantic-versioning).
+
+ ```json:title=package.json
+ {
+ "version": "1.0.0",
+ }
+ ```
+
+- Include a `keywords` field in your adapter's `package.json`, containing `gatsby`, `gatsby-plugin`, and `gatsby-adapter`. This way the adapter can be found through the [plugin library](/plugins/).
+
+ ```json:title=package.json
+ {
+ "keywords": [
+ "gatsby",
+ "gatsby-plugin",
+ "gatsby-adapter"
+ ],
+ }
+ ```
+
+- Include a `peerDependencies` field in your adapter's `package.json`, containing the `gatsby` version range that your adapter is compatible with.
+
+ For example, if your adapter supports Gatsby 5 only (e.g. it uses an API only available in Gatsby 5), use:
+
+ ```json:title=package.json
+ {
+ "peerDependencies": {
+ "gatsby": "^5.0.0"
+ }
+ }
+ ```
+
+ If Gatsby releases a new major version and your adapter doesn't require the new changes, you can mark your adapter as compatible with specific versions. For example, to mark your adapter as compatible with Gatsby 5 and Gatsby 6:
+
+ ```json:title=package.json
+ {
+ "peerDependencies": {
+ "gatsby": "^5.0.0 || ^6.0.0"
+ }
+ }
+ ```
+
+- Add a `build` script to your adapter's `package.json`. The `build` script should compile your source code to **CommonJS (CJS)** into a `dist` folder. If you're authoring the code in TypeScript, also consider generating type definitions. If you're authoring the code in CJS already there is no need for a `build` script.
+
+ Depending on your tooling (e.g. [microbundle](https://github.com/developit/microbundle), [Babel](https://babeljs.io/), [Parcel](https://parceljs.org/), [tsup](https://github.com/egoist/tsup)) adjust your build script:
+
+ ```json:title=package.json
+ {
+ "scripts": {
+ "build": "your-build-script",
+ }
+ }
+ ```
+
+ Since your compiled information will be in the `dist` folder, you need to also add a `main` and `files` key to the `package.json`.
+
+ ```json:title=package.json
+ {
+ "main": "./dist/index.js",
+ "files": [
+ "./dist/*"
+ ],
+ }
+ ```
+
+ If you've generated TypeScript types, consider [adding a `types` key](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html).
+
+- Add a `prepare` script to your adapter's `package.json` that runs before `npm publish`. If the `build` script doesn't automatically clear the `dist` folder before a new build, add an additional `clean` script. This ensures that old artifacts aren't accidentally published. For example, if you rename a file and don't run `clean`, the old file will still be published through `dist`. You could use [del-cli](https://www.npmjs.com/package/del-cli) to achieve this. It would look something like this:
+
+ ```json:title=package.json
+ {
+ "scripts": {
+ "clean": "del-cli dist",
+ "build": "your-build-script",
+ "prepare": "npm run clean && npm run build"
+ }
+ }
+ ```
+
+- Follow the other recommendations from npm's [Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file) documentation, e.g. adding a `description` or `author` field.
+
+## Additional resources
+
+- [gatsby-adapter-netlify source code](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-adapter-netlify)
+- [Adapters](/docs/how-to/previews-deploys-hosting/adapters/)
+- [Zero-Configuration Deployments](/docs/how-to/previews-deploys-hosting/zero-configuration-deployments/)
+- [Gatsby Adapters RFC](https://github.com/gatsbyjs/gatsby/discussions/38231)
diff --git a/docs/docs/how-to/previews-deploys-hosting/headers.md b/docs/docs/how-to/previews-deploys-hosting/headers.md
new file mode 100644
index 0000000000000..233f34a5f574d
--- /dev/null
+++ b/docs/docs/how-to/previews-deploys-hosting/headers.md
@@ -0,0 +1,215 @@
+---
+title: HTTP Headers
+tableOfContentsDepth: 2
+---
+
+## Introduction
+
+You can set custom [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) on the response of a given path. This allows you to modify the caching behavior or configure access control. You can apply HTTP headers to static routes and redirects.
+
+This feature was added in `gatsby@5.12.0`.
+
+## Usage
+
+Use the `headers` config option inside `gatsby-config`:
+
+```js:title=gatsby-config.js
+module.exports = {
+ headers: [
+ {
+ source: `/slug`,
+ headers: [
+ {
+ key: `x-custom-header`,
+ value: `Hello World`,
+ }
+ ]
+ }
+ ]
+}
+```
+
+The `headers` option accepts an array of objects in the following shape:
+
+- `source`: A request path pattern. See [path matching](#path-matching) for more details on its syntax. The paths `/slug` and `/slug/` are equivalent since Gatsby normalizes [trailing slashes](/docs/reference/config-files/gatsby-config/#trailingslash).
+- `headers`: An array of objects in the following shape:
+ - `key`: The case-insensitive name of the header
+ - `value`: The value of the header
+
+## Overriding behavior
+
+The order in which you insert values into `headers` doesn't matter because Gatsby determines the specificity of each `source` path.
+
+If two headers match the same path and set the same header `key`, the entry with the more specific `source` path will override the other. Examples of the overriding behavior are included [below](#examples).
+
+Once entries with matching paths are handled, all header entries are merged together into one array of headers.
+
+Generally speaking, the headers get created in this order. Note that static entries can override the first two:
+
+1. [Default](#defaults) headers
+1. Entries with [path matching](#path-matching) on `source`
+1. Entries with a static `source` path
+
+### Examples
+
+To help illustrate how header overrides work, here are some examples. The `input` represents what you can pass to the `headers` config option and the `output` is what Gatsby produces for the given matched path.
+
+#### Non-overlapping keys
+
+```js
+const input = [
+ {
+ source: `*`,
+ headers: [
+ {
+ key: `x-another-custom-header`,
+ value: `win`,
+ },
+ ],
+ },
+ {
+ source: `/some-path/`,
+ headers: [
+ {
+ key: `x-custom-header`,
+ value: `win`,
+ },
+ ],
+ },
+]
+
+// => Match for path "/some-path/"
+
+const output = [
+ { key: `x-another-custom-header`, value: `win` },
+ { key: `x-custom-header`, value: `win` },
+]
+```
+
+#### Overlapping keys
+
+This example also shows that static entries will override ones with path matching.
+
+```js
+const input = [
+ {
+ source: `/some-path/`,
+ headers: [
+ {
+ key: `x-custom-header`,
+ value: `win`,
+ },
+ ],
+ },
+ {
+ source: `*`,
+ headers: [
+ {
+ key: `x-custom-header`,
+ value: `lose`,
+ },
+ ],
+ },
+]
+
+// => Match for path "/some-path/"
+
+const output = [{ key: `x-custom-header`, value: `win` }]
+```
+
+#### Specificity
+
+Gatsby internally adds scores to each path matching entry and sorts the entries by that score — the entry with the highest specificity will override other matching entries. In the following example, `/some-path/:slug` overrides the rest because it's more specific than `*` and `/some-path/*`.
+
+```js
+const input = [
+ {
+ source: `*`,
+ headers: [
+ {
+ key: `x-custom-header`,
+ value: `lose-1`,
+ },
+ ],
+ },
+ {
+ source: `/some-path/*`,
+ headers: [
+ {
+ key: `x-custom-header`,
+ value: `lose-2`,
+ },
+ ],
+ },
+ {
+ source: `/some-path/:slug`,
+ headers: [
+ {
+ key: `x-custom-header`,
+ value: `win`,
+ },
+ ],
+ },
+]
+
+// => Match for path "/some-path/foo"
+
+const output = [{ key: `x-custom-header`, value: `win` }]
+```
+
+## Path matching
+
+As outlined in the previous paragraphs, you can not only define static `source` paths like `/some-path/` but also ones with path matching. This allows you to target more than one path, opening up more flexibility. You can currently use two path matchers:
+
+- Dynamic: Matches a path segment (no nested paths)
+- Wildcard: Matches every path segment after its definition
+
+### Dynamic path
+
+You can use a colon (`:`) to declare a dynamic path. For example, `/some-path/:slug` will match `/some-path/foo` and `/some-path/bar`.
+
+```js:title=gatsby-config.js
+module.exports = {
+ headers: [
+ {
+ source: `/some-path/:slug`,
+ headers: [
+ {
+ key: `x-custom-header`,
+ value: `Hello World`,
+ }
+ ]
+ }
+ ]
+}
+```
+
+### Wildcard path
+
+You can use an asterisk (`*`) to declare a wildcard path. For example, `/some-path/*` will match `/some-path/foo` and `/some-path/foo/bar`.
+
+```js:title=gatsby-config.js
+module.exports = {
+ headers: [
+ {
+ source: `/some-path/*`,
+ headers: [
+ {
+ key: `x-custom-header`,
+ value: `Hello World`,
+ }
+ ]
+ }
+ ]
+}
+```
+
+## Defaults
+
+By default, Gatsby applies HTTP caching headers to its assets following the guide [Caching Static Sites](/docs/how-to/previews-deploys-hosting/caching/). You can find the specific values [on GitHub](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/adapter/constants.ts).
+
+You can use the `headers` option to override these defaults.
+
+## Additional resources
+
+- [HTTP Headers MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)
diff --git a/docs/docs/how-to/previews-deploys-hosting/zero-configuration-deployments.md b/docs/docs/how-to/previews-deploys-hosting/zero-configuration-deployments.md
new file mode 100644
index 0000000000000..33480d27c9bae
--- /dev/null
+++ b/docs/docs/how-to/previews-deploys-hosting/zero-configuration-deployments.md
@@ -0,0 +1,34 @@
+---
+title: Zero-Configuration Deployments
+---
+
+## Introduction
+
+Zero-configuration deployments are powered by [adapters](/docs/how-to/previews-deploys-hosting/adapters/). If you use one of the [supported deployment platforms](#supported-deployment-platforms), Gatsby automatically installs and uses the correct adapter when you deploy your project.
+
+This feature was added in `gatsby@5.12.0`.
+
+## Supported deployment platforms
+
+Gatsby currently supports these platforms for zero-configuration deployments:
+
+- [gatsby-adapter-netlify](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-adapter-netlify) for [Netlify](https://www.netlify.com/)
+
+### Manually installing the adapter
+
+If you plan on staying on a specific deployment platform, consider installing the adapter to your `dependencies`. This will give you faster and more robust installs.
+
+If your adapter provides options that you can set, you must manually install the adapter to your `dependencies` to change any of the values. Read the [adapters guide](/docs/how-to/previews-deploys-hosting/adapters/) to learn how to use an adapter.
+
+If you plan on using a specific deployment platform for a long period of time, you may also want to install the adapter to your `dependencies`. This will give you faster and more robust installs.
+
+## Adding additional adapters
+
+Gatsby's zero-configuration deployment setup is controlled through an [`adapters.js`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/adapters.js) file. If you followed the [Creating an Adapter guide](/docs/how-to/previews-deploys-hosting/creating-an-adapter/) and want to add your adapter to this manifest, you can open a pull request.
+
+**Please note:** While we welcome all pull requests, there is no guarantee that all adapters will be added to the official manifest. The Gatsby team will review your adapter and provide feedback as appropriate.
+
+## Additional resources
+
+- [Adapters](/docs/how-to/previews-deploys-hosting/adapters/)
+- [Creating an Adapter](/docs/how-to/previews-deploys-hosting/creating-an-adapter/)
diff --git a/docs/docs/reference/config-files/gatsby-config.md b/docs/docs/reference/config-files/gatsby-config.md
index dcd51557e7bd4..9ee07e3740af8 100644
--- a/docs/docs/reference/config-files/gatsby-config.md
+++ b/docs/docs/reference/config-files/gatsby-config.md
@@ -2,10 +2,10 @@
title: Gatsby Config API
---
-The file `gatsby-config.js`/`gatsby-config.ts` defines your site's metadata, plugins, and other general configuration. This file should be in the root of your Gatsby site. You can author the file in JavaScript (CommonJS or [ES Modules (ESM)](/docs/how-to/custom-configuration/es-modules/) syntax) or [TypeScript](/docs/how-to/custom-configuration/typescript/#gatsby-configts).
+The `gatsby-config` defines your site's metadata, plugins, and other general configuration. This file should be in the root of your Gatsby site. You can author the file in JavaScript (CommonJS or [ES Modules (ESM)](/docs/how-to/custom-configuration/es-modules/) syntax) or [TypeScript](/docs/how-to/custom-configuration/typescript/#gatsby-configts), for example `gatsby-config.js`, `gatsby-config.mjs`, or `gatsby-config.ts`.
If you created a Gatsby site with the `npm init gatsby` command, there should already be a sample configuration file in your site's directory.
-_Note: There are many sample configs which may be helpful to reference in the different [Gatsby Example Websites](https://github.com/gatsbyjs/gatsby/tree/master/examples)._
+**Note:** There are many sample configs which may be helpful to reference in the different [Gatsby example websites](https://github.com/gatsbyjs/gatsby/tree/master/examples).
## Set up the configuration file
@@ -43,7 +43,7 @@ Read the [ES Modules (ESM) and Gatsby documentation](/docs/how-to/custom-configu
## Configuration options
-Options available to set within `gatsby-config.js` include:
+Options available to set within `gatsby-config` include:
1. [siteMetadata](#sitemetadata) (object)
1. [plugins](#plugins) (array)
@@ -51,6 +51,8 @@ Options available to set within `gatsby-config.js` include:
1. [pathPrefix](#pathprefix) (string)
1. [trailingSlash](#trailingslash) (string)
1. [graphqlTypegen](#graphqltypegen) (boolean)
+1. [adapter](#adapter) (object)
+1. [headers](#headers) (array)
1. [polyfill](#polyfill) (boolean)
1. [mapping](#mapping-node-types) (object)
1. [proxy](#proxy) (object)
@@ -159,7 +161,7 @@ module.exports = {
## pathPrefix
-It's common for sites to be hosted somewhere other than the root of their domain. Say you have a Gatsby site at `example.com/blog/`. In this case, you would need a prefix (`/blog`) added to all paths on the site.
+It's common for sites to be hosted somewhere other than the root of their domain. Say you have a Gatsby site at `example.com/blog`. In this case, you would need a prefix (`/blog`) added to all paths on the site. The default setting for this option is `""`.
```javascript:title=gatsby-config.js
module.exports = {
@@ -224,6 +226,48 @@ You can overwrite the search paths, which contain documents that should be scann
By default, `graphqlTypegen` is only run during `gatsby develop`. Set this option to `true` to create the `src/gatsby-types.d.ts` file also during `gatsby build`. Default: `false`.
+## adapter
+
+> Support added in `gatsby@5.12.0`
+
+You can set an [adapter](/docs/how-to/previews-deploys-hosting/adapters/) or configure [zero-configuration deployments](/docs/how-to/previews-deploys-hosting/zero-configuration-deployments/) through the `adapter` setting.
+
+```js:title=gatsby-config.js
+const adapter = require("gatsby-adapter-foo")
+
+module.exports = {
+ adapter: adapter({
+ // adapter options if available
+ })
+}
+```
+
+Read the [adapters guide](/docs/how-to/previews-deploys-hosting/adapters/) to learn more.
+
+## headers
+
+> Support added in `gatsby@5.12.0`
+
+You can set custom HTTP headers on the response of a given path.
+
+```js:title=gatsby-config.js
+module.exports = {
+ headers: [
+ {
+ source: `/some-path`,
+ headers: [
+ {
+ key: `x-custom-header`,
+ value: `Hello World`,
+ }
+ ]
+ }
+ ]
+}
+```
+
+Read the [HTTP headers guide](/docs/how-to/previews-deploys-hosting/headers/) to learn more about header syntax, options, and behaviors.
+
## polyfill
Gatsby uses the ES6 Promise API. Because some browsers don't support this, Gatsby includes a Promise polyfill by default.
diff --git a/docs/docs/reference/gatsby-cli.md b/docs/docs/reference/gatsby-cli.md
index 99052e8c91650..821a147201f51 100644
--- a/docs/docs/reference/gatsby-cli.md
+++ b/docs/docs/reference/gatsby-cli.md
@@ -55,6 +55,7 @@ Options include:
| `-o`, `--open` | Open the site in your (default) browser for you |
| `-S`, `--https` | Use HTTPS |
| `--inspect` | Opens a port for debugging |
+| `--verbose` | Turn on verbose output |
To set up HTTPS, follow the [Local HTTPS guide](/docs/local-https/).
@@ -93,6 +94,7 @@ Options include:
| `--open-tracing-config-file` | Tracer configuration file (OpenTracing compatible). See [Performance Tracing](/docs/performance-tracing/) |
| `--graphql-tracing` | Trace (see above) every graphql resolver, may have performance implications. |
| `--no-color`, `--no-colors` | Disables colored terminal output |
+| `--verbose` | Turn on verbose output |
In addition to these build options, there are some optional [build environment variables](/docs/how-to/local-development/environment-variables/#build-variables) for more advanced configurations that can adjust how a build runs. For example, setting `CI=true` as an environment variable will tailor output for [dumb terminals](https://en.wikipedia.org/wiki/Computer_terminal#Dumb_terminals).
diff --git a/packages/gatsby/src/redux/actions/public.js b/packages/gatsby/src/redux/actions/public.js
index 42caf143d6fa8..e310857219774 100644
--- a/packages/gatsby/src/redux/actions/public.js
+++ b/packages/gatsby/src/redux/actions/public.js
@@ -1306,16 +1306,13 @@ const maybeAddPathPrefix = (path, pathPrefix) => {
}
/**
- * Create a redirect from one page to another. Redirects work out of the box with Gatsby Cloud. Read more about
- * [working with redirects on Gatsby Cloud](https://support.gatsbyjs.com/hc/en-us/articles/1500003051241-Working-with-Redirects).
- * If you are hosting somewhere other than Gatsby Cloud, you will need a plugin to integrate the redirect data with
- * your hosting technology e.g. the [Netlify
- * plugin](/plugins/gatsby-plugin-netlify/), or the [Amazon S3
- * plugin](/plugins/gatsby-plugin-s3/). Alternatively, you can use
- * [this plugin](/plugins/gatsby-plugin-meta-redirect/) to generate meta redirect
- * html files for redirecting on any static file host.
- * Keep the redirects configuration in sync with trailing slash configuration from
- * [Gatsby Config API](/docs/reference/config-files/gatsby-config/#trailingslash).
+ * Create a redirect from one page to another.
+ *
+ * Redirects must be implemented by your deployment platform (e.g. Gatsby Cloud, Netlify, etc.). You can use an [adapter](/docs/how-to/previews-deploys-hosting/adapters/) or plugins for this. Alternatively, you can use [gatsby-plugin-meta-redirect](/plugins/gatsby-plugin-meta-redirect/) to generate meta redirect HTML files for redirecting on any static file host.
+ *
+ * You can read the source code of [gatsby-adapter-netlify](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-adapter-netlify) to see how redirects are implemented on Netlify. Redirects also work out of the box on Gatsby Cloud.
+ *
+ * Keep the redirects configuration in sync with trailing slash configuration from [Gatsby Config API](/docs/reference/config-files/gatsby-config/#trailingslash).
*
* @param {Object} redirect Redirect data
* @param {string} redirect.fromPath Any valid URL. Must start with a forward slash
@@ -1332,12 +1329,14 @@ const maybeAddPathPrefix = (path, pathPrefix) => {
* // Generally you create redirects while creating pages.
* exports.createPages = ({ graphql, actions }) => {
* const { createRedirect } = actions
+ *
* createRedirect({ fromPath: '/old-url/', toPath: '/new-url/', isPermanent: true })
* createRedirect({ fromPath: '/url/', toPath: '/zn-CH/url/', conditions: { language: 'zn' }})
* createRedirect({ fromPath: '/url/', toPath: '/en/url/', conditions: { language: ['ca', 'us'] }})
* createRedirect({ fromPath: '/url/', toPath: '/ca/url/', conditions: { country: 'ca' }})
* createRedirect({ fromPath: '/url/', toPath: '/en/url/', conditions: { country: ['ca', 'us'] }})
* createRedirect({ fromPath: '/not_so-pretty_url/', toPath: '/pretty/url/', statusCode: 200 })
+ *
* // Create pages here
* }
*/