Admin previews

To set up previews, go to development -> gatsby in WordPress and enter the public frontend URL for your site.

...That's all the steps! Clicking "Preview Changes" from the post/page edit screen now works!

Wordsby Img

You need to use Wordsby Img to make images show up in previews. Because the previews use live REST api data, they wont have any graphql magic.

yarn add wordsby-components

import { Img } from "wordsby-components";

Query as if you were using the regular Gatsby Img component but pass in the entire field structure instead of passing fluid or fixed.

query {
...
image {
        localFile {
        childImageSharp {
            fixed(width: 136, quality: 100) {
            ...GatsbyImageSharpFixed_withWebp_tracedSVG
            }
        }
    }
}
...
}

<Img field={image} />

Wordsby Img checks the field you've passed in to see if it has a fluid or fixed gatsby-image query. If it does it adds the Gatsby Img component. If it doesn't, it passes through the field image URL of the hi-res image to an img tag wrapped in some markup/styles that emulate Gatsby Img.

How previews work

Wordsby builds a page on your site for every template at the path /preview/[template_slug]. These pages have a noindex metatag attached to them and they're removed from Gatsby's internal sitemap so they wont show up on google or in your sitemap.xml. If a user somehow ends up on one of these pages, they're redirected to the home page.

When you click "Preview Changes", WordPress makes an internal REST api call to the post revision of your preview data, an iframe with the right preview template page is loaded up, and the REST api response is passed to the iframe using paypals post-robot.

This is possible because unlike gatsby-source-wordpress, we have a single graphql endpoint that encompasses all of our posts and pages (wordsbyCollections). This is also what allows us to switch any page/post to any template without the site build failing. Because of this, the only live preview data will come from that specific graphql query. Don't rename wordsbyCollections in your page query or you wont get any preview data.

wordsbyCollections(ID: $id) { # good
  ...
}
dontDoThis: wordsbyCollections(ID: $id) { # not good for previews
  ...
}
thisIsFine: allWordsbyCollections(filter: {post_type: {eq: "post"}}) { # this is good
  ... # you can't live preview this data anyway. Static data will still show from here
}

Using persistent layouts with previews

Previews work by using React.cloneElement() to manipulate the page props that are passed down. Sometimes if a layout is wrapped around your page in between preview and your page, previews will stop working. The solution is to make sure your layout plugin is added after gatsby-plugin-wordsby in your gatsby-config.js file.

Debugging previews

If you're having issues with your previews you can debug with the following steps.

1. Add define('DANGEROUS__WORDSBY_PUBLIC_PREVIEWS', true); to your wp-config.php.
2. Run gatsby develop
3. Open your WordPress site and click preview from a page or post with the template you want to debug.
4. The correct template will open at localhost:8000/preview/... and populate itself with preview data.
5. Once you're finished, remove define('DANGEROUS__WORDSBY_PUBLIC_PREVIEWS', true); from your wp-config.php.

Usage with gatsby-plugin-netlify

If you're using Netlify and the plugin gatsby-plugin-netlify, previews will be broken due to security headers disallowing cross origin iframes. This is good but we still want to be able to preview our gatsby site (using an iframe) from WordPress. Configure your plugin in gatsby-config.js as follows:

    {
      resolve: "gatsby-plugin-netlify",
      options: {
        headers: {
          "/*": [
            // these headers are default except x-frame-options is omitted to allow previewing the site via iframe
            `X-XSS-Protection: 1; mode=block`,
            `X-Content-Type-Options: nosniff`
          ]
        },
        mergeSecurityHeaders: false
      }
    },