chore(docs): Adapters

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 `[email protected]`.
+
+## 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/)

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/)