Open navClose nav

Instant Previews

With instant previews, you can take advantage of your static site generator’s built-in “watch” or incrementally-updating mode to dramatically reduce the time it takes to refresh a Forestry preview, providing a shorter feedback cycle for editors working on your site.

Adding an Instant Preview

Instant previews are configured via a build command.
To use instant previews, navigate to Settings > Previews.

Default Instant Preview Settings

Most of the time, you shouldn’t have to change the defaults. When you pick up an SSG on import, we automatically add a default build commands. We will set a matching preview environment for you, but your can always pick up a different one or bring your own custom Docker image.

Forestry default preview environements

Customize your settings

You can edit the command used to run your preview by editing the build command field.

Preview settings example for a Gatsby site

Your instant previewing command needs to be a “watch” style command that will start a process to watch for changes to your files, and rebuild your site automatically. This will most likely be the command that a developer would run in their local environment when working on the site, such as hugo server or npm run develop.

  1. Your preview needs to run on 0000:8080 network interface
  2. Commands for any NodeJS-based static site generator needs to be run as an npm script.
  3. If your site lives in a subfolder, you need to setup working directory and output path accordingly.

Defaults server commands

hugo server -D -E -F --port 8080 --bind 0.0.0.0 --renderToDisk -d public
bundle exec jekyll serve --drafts --unpublished --future --port 8080 --host 0.0.0.0 -d _site
vuepress dev --port 8080 --host 0.0.0.0
gatsby develop -p 8080 -H 0.0.0.0
gridsome develop
eleventy --serve --port 8080 --output=dist
hexo server -p 8080
HugoJekyllVuePressGatsbyGridsomeEleventyHexo

Eleventy: to tell BrowserSync to bind to 0.0.0.0, amend your Eleventy configuration file with something like:

/* Run serve on 0.0.0.0 on staging */
if( process.env.ELEVENTY_ENV == "staging" ) {
  eleventyConfig.setBrowserSyncConfig({
    host: "0.0.0.0"
  });
}

Don’t forget to set ELEVENTY_ENV environment variable to staging in the preview settings.

Start the preview

When you click on the Start Preview button, your preview will spin up. Build time will mostly depend on your stack and your content. It can go from a few seconds on Hugo or Eleventy to several minutes on a large Jekyll or Gatsby site.

Preview environment started

Once your preview environment is running fine, your editors will be able to click to preview icon button, that will open a preview of your website in a new browser tab.

Preview still not running? See our troubleshooting section to do some checks.

Live Reloading

Forestry’s live previewing relies on the built-in live browser reloading provided by your preview process. Instant previews have been tested and confirmed working with Browsersync and LiveReload.

Preview Settings in .forestry/settings.yml

Alternatively, you can setup your instant previews directly from your configuration file in .forestry/settings.yml in the build section.

Here’s an example of a build section in the .forestry/settings.yml file:

build:
  preview_docker_image: node:10 # Our project use a node-based SSG
  install_dependencies_command: npm install # We manage dependencies through NPM
  instant_preview_command: npm start # Our preview script is aliased to npm start script in our package.json
  mount_path: "/srv" # Don't touch this unless you use a custom Docker image
  working_dir: "/srv/src" # Our project lives in a `src` subfolder
  preview_output_directory: "src/dist" # we build our site in `dist` folder
  preview_env:
  - ENV=staging # we don't want to optimize for production

Instant Preview URLs

When you click the preview button on a piece of content, Forestry will attempt to determine which URL to open by temporarily inserting a unique preview token in the markdown body. There are two situations where this won’t work:

If the Layout Doesn’t Use Markdown Body

You may have some layouts that don’t utilize the body of the markdown file. This happens when you instead build the page entirely from front matter data, such as when you use blocks.

For these layouts, Forestry also inserts a special front matter value that you can include in these layouts to improve Forestry’s preview URL behavior. By outputting the contents of the forestry_instant_preview_id front matter key in your layout, Forestry will be able to identified the content being previewed. You can output this value anywhere between the opening and closing <body> tags of your HTML, and it is recommended to add it as an HTML comment. If your HTML is being run through a minifier that strips comments, it’s fine to insert it differently, such as in a <meta> tag.

Be aware that forestry_preview_id will only be inserted in one file at a time, and won’t be guaranteed to be there, so your code should check for it before outputting its value.

{{ with .Params.forestry_instant_preview_id }}
  {{- safeHTML (printf "<meta property='forestry_instant_preview_id' content='%s'>" .) -}}
{{ end -}}

HTML comments in Hugo must be filtered with safeHTML in order to be output to the document.

{% if page.forestry_instant_preview_id != "" %}
<meta property="forestry_instant_preview_id" content="{{ page.forestry_instant_preview_id }}">
{% endif %}
HugoJekyll

If the SSG Doesn’t Write Content to HTML Files in Dev Mode

If your static site generator doesn’t write content updates to HT%M (such as when using gatsby develop,) this won’t work and the preview will always open the home page of your site.


Last updated on January 5, 2019