docs(gatsby-source-wordpress): document content sync (#32768)

* document new preview loader for WP

packages/gatsby-source-wordpress/docs/features/preview.md

@@ -1,6 +1,6 @@
 # Preview
 
-This plugin supports [Preview](https://www.gatsbyjs.com/preview/) and has been designed to replicate the normal WordPress admin preview experience as closely as possible.
+This plugin supports [Preview](https://www.gatsbyjs.com/preview/) and has been designed to make the WordPress admin preview experience as seamless as possible.
 
 ## How Preview works
 
@@ -10,35 +10,14 @@ When configured properly by a developer, preview should function almost identica
 
 You can find our tutorial on setting up WPGatsby [here](../tutorials/configuring-wp-gatsby.md#setting-up-preview). Part-way down the page there are instructions you can follow on setting up Preview.
 
-## File System Route API
+## Debugging the build process of Previews
 
-The [File System Route API](https://www.gatsbyjs.com/docs/reference/routing/file-system-route-api/) is not currently supported with WP Previews because it does not call the `onCreatePage` API which this plugin relies on. Follow [this issue](https://github.com/gatsbyjs/gatsby/issues/29361) for updates or [vote for this feature](https://gatsby.canny.io/gatsby-cloud/p/support-filesystem-route-api-alongside-gatsby-source-wordpress).
+If you enable the plugin option `options.debug.preview` by setting it to `true`, you will see additional logging through the Preview build process with information such as the contents of the webhook body that was sent to Gatsby, the preview node data, and the list of preview actions that were pulled from WordPress. See the [plugin options](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wordpress/docs/plugin-options.md#debugpreview) documentation for more info.
 
 ## Gutenberg and ACF
 
 Note that if you use these two together, you cannot preview ACF data. This is a core WordPress Gutenberg issue. Follow https://github.com/WordPress/gutenberg/issues/16006 for more information. If you use ACF and would like to preview data changes, use the Classic Editor plugin for now.
 
-## Template safety
-
-Be sure to guard against missing data in your templates using optional chaining so that missing data doesn't cause template errors. Trying to access properties on undefined will break your preview. For example, if you try to access `wpPost.acfFieldGroup.hero.content` but your Preview template receives `null` for `wpPost.acfFieldGroup`, your preview template will break.
-
-To guard against this you can use optional chaining by writing `wpPost?.acfFieldGroup?.hero?.content` instead.
-
-## Debugging Previews in React
-
-Since a Previewed post might have a lot less data attached to it than what you're testing with during development, you might get errors in previews when that data is missing. You can debug your previews by running Gatsby in preview mode locally.
-
-- Run Gatsby in refresh mode with `ENABLE_GATSBY_REFRESH_ENDPOINT=true gatsby develop`
-- Install ngrok with `npm i -g ngrok`
-- In a new terminal window run `ngrok http 8000`
-- In your WP instance's GatsbyJS settings, set your Preview instance URL to `https://your-ngrok-url.ngrok.io` and your Preview webhook to `https://your-ngrok-url.ngrok.io/__refresh`
-
-Now when you click the preview button in `wp-admin` it will use your local instance of Gatsby. You can inspect the preview template to see which Gatsby page is being loaded in the preview iframe and open it directly to do further debugging.
-
-## Debugging the build process of Previews
-
-If you enable the plugin option `options.debug.preview` by setting it to `true`, you will see additional logging through the Preview build process with information such as the contents of the webhook body that was sent to Gatsby, the preview node data, and the list of preview actions that were pulled from WordPress. See the [plugin options](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wordpress/docs/plugin-options.md#debugpreview) documentation for more info.
-
 ## Common gatsby-node.js problems that break previews
 
 ### 1. When querying for nodes, the previewed node is filtered out
@@ -85,42 +64,7 @@ exports.createPages = async ({ graphql }) => {
 }
 ```
 
-### 2. Not including the node id in pageContext
-
-It is currently a hard requirement that the node id is added to pageContext.
-
-```js
-exports.createPages = async ({ graphql, actions }) => {
-  const graphqlResult = await graphql(/* GraphQL */ `
-    query {
-      allWpPost {
-        edges {
-          node {
-            id
-            uri
-          }
-        }
-      }
-    }
-  `)
-
-  graphqlResult.data.allWpPost.edges.map(({ node }) => {
-    actions.createPage({
-      path: node.uri,
-      component: require.resolve(`./src/components/dog.js`),
-      context: {
-        id: node.id, // if this is not included, previews will not work.
-      },
-    })
-  })
-}
-```
-
-### 3. Context stuffing
-
-Some sites circumvent using page queries by querying for all data in `gatsby-node.js` and passing the result as page context data when calling `createPage`. This breaks previews and incremental builds and is discouraged. You should only make GraphQL queries for page data in [page queries](https://www.gatsbyjs.com/docs/recipes/querying-data#querying-data-with-a-page-query).
-
-### 4. Using createPagesStatefully
+### 2. Using createPagesStatefully
 
 The correct Node API for creating pages is [`createPages`](https://www.gatsbyjs.com/docs/reference/config-files/gatsby-node/#createPages), using `createPagesStatefully` will prevent previews from working.
 
@@ -180,7 +124,7 @@ The preset (as found in src/models/gatsby-api.ts) is:
 
 ## How Preview works behind the scenes
 
-When the WP "preview" button is pressed, a JWT is generated (with an expiry time of 1 hour) and POST'ed to the Gatsby Preview instance webhook. The Preview instance then uses this short-lived JWT to request a list of pending previews for all users. Gatsby starts processing each pending preview. At the same time, WordPress automatically opens the WP preview template which has been overridden by WPGatsby. Within the WP preview template you will see the admin bar at the top of the page as usual. The WordPress preview template displays a loader and waits for Gatsby to send back the preview status for the preview you're observing - it will receive a response when the preview has been processed on the Gatsby side. On the Gatsby side, it matches up the node being previewed with the Gatsby page that was created from it, once that page has been updated or created, it sends back the Gatsby page path for that page. WordPress then starts watching for the changed page to be deployed. Once it's deployed, the WordPress preview template loads the right Gatsby page in an iframe and removes the loader. In the case that there are errors on the Gatsby side, or no page is created for the node that's being previewed, Gatsby will send back an appropriate status and WPGatsby will display an error in the browser with instructions on how to resolve the issue.
+When the WP "preview" button is pressed, a JWT is generated (with an expiry time of 1 hour) and POST'ed to the Gatsby Preview instance webhook. The Preview instance then uses this short-lived JWT to request a list of pending previews for all users. Gatsby starts processing each pending preview. At the same time, WordPress automatically opens the WP preview template which has been overridden by WPGatsby to redirect to Gatsby Cloud's Content Sync service. This service handles the loading/error states and will redirect the user to the right page when it's been built.
 
 ## Preview Security Considerations
 

packages/gatsby-source-wordpress/docs/tutorials/configuring-previews-legacy.md

@@ -0,0 +1,47 @@
+## Setting Up Preview
+
+Once configured in the GatsbyJS settings page in wp-admin, Previews will work out of the box as long as your Gatsby pages have the corresponding node id as part of their pageContext. See [this starter's gatsby-node.js](https://github.com/gatsbyjs/gatsby/blob/master/starters/gatsby-starter-wordpress-blog/tree/master/gatsby-node.js) for an example of how to set up your Gatsby pages. See the [feature page on Preview](../features/preview.md) for more information about how Preview works, considerations you should keep in mind while writing Preview-ready templates, and how to debug Preview templates.
+
+### Connecting Preview
+
+To get started, set up a Preview instance on [Gatsby Cloud](https://www.gatsbyjs.com/) or set up your [self-hosted Preview instance](https://www.gatsbyjs.org/docs/running-a-gatsby-preview-server/). If you want to try out Preview but aren't sure whether you want to subscribe to Gatsby Cloud or self-host, you can start a free 2 week Gatsby Cloud trial with no credit card to help you make up your mind!
+
+#### WordPress Settings
+
+Navigate to your GatsbyJS WordPress settings by visiting this path in your WP instance `/wp-admin/options-general.php?page=gatsbyjs` or by hovering on "Settings" in the WordPress admin menu and clicking on "GatsbyJS".
+
+You will see 4 fields related to Gatsby Preview. "Enable Gatsby Preview?", "Preview Instance", "Preview Webhook", and "Preview JWT secret".
+
+If you don't see this settings page, or you don't see these 4 fields, make sure the latest version of [WPGatsby](https://github.com/gatsbyjs/wp-gatsby) is installed in your WordPress instance.
+
+![wp-gatsbyjs-preview-settings](../../docs/assets/wp-gatsbyjs-preview-settings.png)
+
+#### 1. Check the "Enable Gatsby Preview?" Checkbox
+
+When this checkbox is checked, WPGatsby will override the functionality of the WordPress "preview" button in the page/post edit screen. Clicking "preview" will open the regular WordPress preview template, but the WP frontend will be replaced with your Gatsby Preview instance.
+
+#### 2. Fill the "Preview Instance" Field
+
+This field should be filled with the public frontend URL of your Gatsby Preview instance.
+
+To find your **Preview Instance URL**, navigate to the "Preview" tab in [Gatsby Cloud](https://www.gatsbyjs.com/dashboard/sites), wait for your first Preview build to complete, and then copy the frontend URL from above the build history list in the center of the page.
+
+![Gatsby Cloud Preview frontend URL Screenshot](../../docs/assets/gatsby-cloud-preview-frontend-url.png)
+
+#### 3. Fill the "Preview Webhook" Field
+
+You can find your **Preview webhook** by navigating to "Site Settings" in Gatsby Cloud and then navigating to "Webhooks" via the left-side menu.
+
+![Gatsby Cloud Preview Webhook URL](../../docs/assets/gatsby-cloud-preview-webhook-url.png)
+
+#### 4. Double check the "Preview JWT secret" field
+
+This field should be filled for you automatically with a cryptocraphically secure key when you install WPGatsby. If this field is empty, feel free to copy a salt from the [WordPress salts generator page](https://api.wordpress.org/secret-key/1.1/salt) and use that as your JWT secret key.
+
+This secret key is used to authenticate short-lived JWT tokens when you're viewing previews from WordPress so a very strong key should be used to prevent security issues.
+
+### Using your Preview
+
+Now that you've configured WPGatsby for your Preview instance, visit a page or post you'd like to preview, edit it, and press "preview" in the top right corner of the edit screen like you usually would in WordPress. You should see a new tab pop open with your Preview instance and previewed content visible!
+
+:point_left: [Back to Features](./index.md)

packages/gatsby-source-wordpress/docs/tutorials/configuring-wp-gatsby.md

@@ -27,17 +27,19 @@ Now that your Builds webhook is set up, when content is updated in WordPress you
 
 ## Setting Up Preview
 
-Once configured in the GatsbyJS settings page in wp-admin, Previews will work out of the box as long as your Gatsby pages have the corresponding node id as part of their pageContext. See [this starter's gatsby-node.js](https://github.com/gatsbyjs/gatsby/blob/master/starters/gatsby-starter-wordpress-blog/tree/master/gatsby-node.js) for an example of how to set up your Gatsby pages. See the [feature page on Preview](../features/preview.md) for more information about how Preview works, considerations you should keep in mind while writing Preview-ready templates, and how to debug Preview templates.
+Once configured in the GatsbyJS settings page in wp-admin, Previews will work out of the box. See the [feature page on Preview](../features/preview.md) for more information about how Preview works. WPGatsby has been updated to use Gatsby Cloud's new Content Sync service, which is a service that handles the loading view, error handling, and redirection for users that are previewing content. Make sure you've upgraded to the latest versions of WPGatsby, `gatsby`, and `gatsby-source-wordpress`. For documentation about legacy previews where the preview loader used to live on the WordPress side [see here](./configuring-previews-legacy.md).
+
+Note that this feature will work on the latest version of Gatsby but will be more reliable on `[email protected]`.
 
 ### Connecting Preview
 
-To get started, set up a Preview instance on [Gatsby Cloud](https://www.gatsbyjs.com/) or set up your [self-hosted Preview instance](https://www.gatsbyjs.org/docs/running-a-gatsby-preview-server/). If you want to try out Preview but aren't sure whether you want to subscribe to Gatsby Cloud or self-host, you can start a free 2 week Gatsby Cloud trial with no credit card to help you make up your mind!
+To get started, set up a Preview instance on [Gatsby Cloud](https://www.gatsbyjs.com/).
 
 #### WordPress Settings
 
 Navigate to your GatsbyJS WordPress settings by visiting this path in your WP instance `/wp-admin/options-general.php?page=gatsbyjs` or by hovering on "Settings" in the WordPress admin menu and clicking on "GatsbyJS".
 
-You will see 4 fields related to Gatsby Preview. "Enable Gatsby Preview?", "Preview Instance", "Preview Webhook", and "Preview JWT secret".
+You will see 5 fields related to Gatsby Preview. "Enable Gatsby Preview?", "Use Gatsby Content Sync?", "Content Sync URL", "Preview Webhook", and "Preview JWT secret".
 
 If you don't see this settings page, or you don't see these 4 fields, make sure the latest version of [WPGatsby](https://github.com/gatsbyjs/wp-gatsby) is installed in your WordPress instance.
 
@@ -47,21 +49,23 @@ If you don't see this settings page, or you don't see these 4 fields, make sure
 
 When this checkbox is checked, WPGatsby will override the functionality of the WordPress "preview" button in the page/post edit screen. Clicking "preview" will open the regular WordPress preview template, but the WP frontend will be replaced with your Gatsby Preview instance.
 
-#### 2. Fill the "Preview Instance" Field
+#### 2. Check the "Use Gatsby Content Sync?" Checkbox
+
+When this checkbox is checked, WPGatsby will use the new Gatsby Cloud Content Sync service for previews. Instead of WPGatsby handling loading previews and redirecting to the right page, Gatsby Cloud will now do it instead. This is optional but recommended as this will become the default in the future and [legacy previews](./configuring-previews-legacy.md) will be removed.
 
-This field should be filled with the public frontend URL of your Gatsby Preview instance.
+#### 3. Fill the "Gatsby Content Sync URL" Field
 
-To find your **Preview Instance URL**, navigate to the "Preview" tab in [Gatsby Cloud](https://www.gatsbyjs.com/dashboard/sites), wait for your first Preview build to complete, and then copy the frontend URL from above the build history list in the center of the page.
+This field should be filled with the Content Sync URL of your Gatsby Preview instance.
 
-![Gatsby Cloud Preview frontend URL Screenshot](../../docs/assets/gatsby-cloud-preview-frontend-url.png)
+To find your **Content Sync URL**, navigate to the "Site Settings" tab in [Gatsby Cloud](https://www.gatsbyjs.com/dashboard/sites), scroll down until you see the "Content Sync URL", and copy the URL displayed there.
 
-#### 3. Fill the "Preview Webhook" Field
+#### 4. Fill the "Preview Webhook" Field
 
 You can find your **Preview webhook** by navigating to "Site Settings" in Gatsby Cloud and then navigating to "Webhooks" via the left-side menu.
 
 ![Gatsby Cloud Preview Webhook URL](../../docs/assets/gatsby-cloud-preview-webhook-url.png)
 
-#### 4. Double check the "Preview JWT secret" field
+#### 5. Double check the "Preview JWT secret" field
 
 This field should be filled for you automatically with a cryptocraphically secure key when you install WPGatsby. If this field is empty, feel free to copy a salt from the [WordPress salts generator page](https://api.wordpress.org/secret-key/1.1/salt) and use that as your JWT secret key.