static-cms/website/content/docs/deploy-preview-links.md

---
group: Workflow
weight: 10
title: Deploy Preview Links
---
When using the editorial workflow, content editors can create and save content without publishing it
to a live site. Deploy preview links provide a way to view live content when it has not been
published, provided that you're using a continuous deployment platform to provide "deploy previews"
of your unmerged content.

## Using deploy preview links

Deploy preview links will work without configuration when all of the following requirements are met:

* Simple CMS version is 2.4.0+ for GitHub support and 2.10.6+ for GitLab/Bitbucket support
* Using editorial workflow
* Have a continuous deployment platform that builds every commit and provides statuses to your repo

Any site created using one of the Deploy to Netlify options on our [starters
page](../start-with-a-template) will automatically meet these criteria (barring any changes made to
your Netlify settings), but you may need to [update](../update-the-cms-version) your Simple CMS version to get the
functionality.

**Note:** If you're using a custom backend (one that is not included with Simple CMS), please check the
documentation for that backend for more information about enabling deploy preview links.

Deploy preview links are provided in the editor toolbar, near the publishing controls:

![Deploy preview link for unpublished content](/img/preview-link-unpublished.png)

### Waiting for builds

Deploy your site preview may take ten seconds or ten minutes, depending on many factors. For maximum
flexibility, Simple CMS provides a "Check for Preview" refresh button when the deploy preview is
pending, which a content editor can use to manually check for a finished preview until it's ready:

![Deploy preview link for unpublished content](/img/preview-link-check.png)

## Configuring preview paths

Deploy preview links point to the site root by default, but you'll probably want them to point to
the specific piece of content that the content editor is viewing. You can do this by providing a
`preview_path` string template for each collection, or for inidividual files in a files collection.

Let's say we have a `blog` collection that stores content in our repo under `content/blog`. The path
to a post in your repo may look like `content/blog/2018-01-new-post.md`, but the path to that post
on your site would look more like: `/blog/2018-01-new-post/`. Here's how you would use
`preview_path` in your configuration for this scenario:

```yaml
collections:
  - name: blog
    folder: content/blog
    slug: {{year}}-{{month}}-{{slug}}
    preview_path: blog/{{slug}}
```

Similarly, for an `about` page in a files collection under `content/pages` which maps to `/about-the-project`
on your site, you would configure `preview_path` like this:

```yaml
collections:
  - name: pages
    files:
      - name: about
        file: content/pages/about.md
        preview_path: about-the-project
```

With the above configuration, the deploy preview URL from your backend will be combined with your
preview path to create a URL to a specific blog post.

**Note:** `{{slug}}` in `preview_path` is different than `{{slug}}` in `slug`. In the `slug`
template, `{{slug}}` is only the url-safe [identifier
field](../configuration-options/#identifier_field), while in the `preview_path` template, `{{slug}}`
is the entire slug for the entry. For example:

```yaml
# for an entry created Jan 1, 2000 with identifier "My New Post!"
collections:
  - name: posts
    slug: {{year}}-{{month}}-{{slug}} # {{slug}} will compile to "my-new-post"
    preview_path: blog/{{slug}} # {{slug}} will compile to "2000-01-my-new-post"
```

### Dates in preview paths

Some static site generators allow URL's to be customized with date parameters - for example, Hugo
can be configured to use values like `year` and `month` in a URL. These values are generally derived
by the static site generator from a date field in the content file. `preview_path` accepts these
parameters as well, similar to the `slug` configuration, except `preview_path` populates date values
based on a date value from the entry, just like static site generators do. Simple CMS will attempt
to infer an obvious date field, but you can also specify which date field to use for `preview_path`
template tags by using
[`preview_path_date_field`](../configuration-options/#preview_path_date_field).

Together with your other field values, dates can be used to configure most URL schemes available
through static site generators.

**Example**

```yaml
# This collection's date field will be inferred because it has a field named `"date"`
collections:
  - name: posts
    preview_path: blog/{{year}}/{{month}}/{{title}}
    fields:
      - { name: title, label: Title }
        { name: date, label: Date, widget: date }
        { name: body, label: Body, widget: markdown }
# This collection requires `path_preview_date_field` because the no obvious date field is available
collections:
  - name: posts
    preview_path: blog/{{year}}/{{month}}/{{title}}
    preview_path_date_field: published_at
    fields:
      - { name: title, label: Title }
        { name: published_at, label: Published At, widget: date }
        { name: body, label: Body, widget: markdown }
```

## Preview links for published content

You may also want preview links for published content as a convenience. You can do this by providing
a `site_url` in your configuration, which will be used in place of the deploy preview URL that a
backend would provide for an unpublished entry. Just as for deploy preview links to unpublished
content, links to published content will use any `preview_path` values that are defined in the
collection configurations.

Preview links for published content will also work if you are not using the editorial workflow.

![Deploy preview link for unpublished content](/img/preview-link-unpublished.png)

## Disabling deploy preview links

To disable deploy preview links, set `show_preview_links` to false in your CMS configuration.

## How it works

Deploy preview links are provided through your CMS backend, and Simple CMS is unopinionated about
where the links come from or how they're created. That said, the general approach for Git backends
like GitHub is powered by "commit statuses". Continuous deployment platforms like Netlify can deploy
a version of your site for every commit that is pushed to your remote Git repository, and then send
a commit status back to your repository host with the URL.

The deploy preview URL provided by a backend will lead to the root of the deployed site. Simple CMS
will then use the `preview_path` template in an entry's collection configuration to build a path to
a specific piece of content. If a `preview_path` is not provided for an entry's collection, the URL
will be used as is.