Add missing content folder
This commit is contained in:
Daniel Lautzenheiser
149
website/content/docs/deploy-preview-links.md
Normal file
149
website/content/docs/deploy-preview-links.md
Normal file
@ -0,0 +1,149 @@
|
||||
---
|
||||
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:
|
||||
|
||||
|
||||
|
||||
### 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:
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user