Feature/remove editorial workflow (#8)
This commit is contained in:
Daniel Lautzenheiser
committed by
GitHub
GitHub
parent
5e6164efc4
commit
10b442428a
@ -95,17 +95,6 @@ backend:
|
||||
|
||||
The configuration above specifies your backend protocol and your publication branch. Git Gateway is an open source API that acts as a proxy between authenticated users of your site and your site repo. (We'll get to the details of that in the [Authentication section](#authentication) below.) If you leave out the `branch` declaration, it defaults to `master`.
|
||||
|
||||
### Editorial Workflow
|
||||
|
||||
**Note:** Editorial workflow works with GitHub repositories, and support for GitLab and Bitbucket is [in beta](/docs/beta-features/#gitlab-and-bitbucket-editorial-workflow-support).
|
||||
|
||||
By default, saving a post in the CMS interface pushes a commit directly to the publication branch specified in `backend`. However, you also have the option to enable the [Editorial Workflow](../configuration-options/#publish-mode), which adds an interface for drafting, reviewing, and approving posts. To do this, add the following line to your Simple CMS `config.yml`:
|
||||
|
||||
```yaml
|
||||
# This line should *not* be indented
|
||||
publish_mode: editorial_workflow
|
||||
```
|
||||
|
||||
### Media and Public Folders
|
||||
|
||||
Simple CMS allows users to upload images directly within the editor. For this to work, the CMS needs to know where to save them. If you already have an `images` folder in your project, you could use its path, possibly creating an `uploads` sub-folder, for example:
|
||||
|
||||
@ -63,16 +63,3 @@ The control component receives one (1) callback as a prop: `onChange`.
|
||||
Both control and preview widgets receive a `getAsset` selector via props. Displaying the media (or its URI) for the user should always be done via `getAsset`, as it returns an AssetProxy that can return the correct value for both medias already persisted on the server and cached media not yet uploaded.
|
||||
|
||||
The actual persistence of the content and medias inserted into the control component is delegated to the backend implementation. The backend will be called with the updated values and a list of assetProxy objects for each field of the entry, and should return a promise that can resolve into the persisted entry object and the list of the persisted media URIs.
|
||||
|
||||
|
||||
## Editorial Workflow implementation
|
||||
|
||||
Instead of adding logic to `CollectionPage` and `EntryPage`, the Editorial Workflow is implemented as Higher Order Components, adding UI and dispatching additional actions.
|
||||
|
||||
Furthermore, all editorial workflow state is managed in Redux - there's an `actions/editorialWorkflow.js` file and a `reducers/editorialWorkflow.js` file.
|
||||
|
||||
### About metadata
|
||||
|
||||
Simple CMS embraces the idea of Git-as-backend for storing metadata. The first time it runs with the `editorial_workflow` setup, it creates a new ref called `meta/_simple_cms`, pointing to an empty, orphan tree.
|
||||
|
||||
Actual data are stored in individual `json` files committed to this tree.
|
||||
|
||||
@ -18,7 +18,6 @@ Individual backends should provide their own configuration documentation, but th
|
||||
| `site_domain` | `location.hostname` (or `cms.netlify.com` when on `localhost`) | Sets the `site_id` query param sent to the API endpoint. Non-Netlify auth setups will often need to set this for local development to work properly. |
|
||||
| `base_url` | `https://api.netlify.com` (GitHub, Bitbucket) or `https://gitlab.com` (GitLab) | OAuth client hostname (just the base domain, no path). **Required** when using an external OAuth server or self-hosted GitLab. |
|
||||
| `auth_endpoint` | `auth` (GitHub, Bitbucket) or `oauth/authorize` (GitLab) | Path to append to `base_url` for authentication requests. Optional. |
|
||||
| `cms_label_prefix` | `simple-cms/` | Pull (or Merge) Requests label prefix when using editorial workflow. Optional. |
|
||||
|
||||
## Creating a New Backend
|
||||
|
||||
|
||||
@ -28,7 +28,7 @@ local_backend: true
|
||||
4. Start your local development server (e.g. run `gatsby develop`).
|
||||
5. Open `http://localhost:<port>/admin` to verify that your can administer your content locally. Replace `<port>` with the port of your local development server. For example Gatsby's default port is `8000`
|
||||
|
||||
**Note:** `netlify-cms-proxy-server` runs an unauthenticated express server. As any client can send requests to the server, it should only be used for local development. Also note that `editorial_workflow` is not supported in this environment.
|
||||
**Note:** `netlify-cms-proxy-server` runs an unauthenticated express server. As any client can send requests to the server, it should only be used for local development.
|
||||
|
||||
### Configure the Simple CMS proxy server port number
|
||||
|
||||
@ -51,16 +51,6 @@ local_backend:
|
||||
allowed_hosts: ['192.168.0.1']
|
||||
```
|
||||
|
||||
## GitLab and BitBucket Editorial Workflow Support
|
||||
|
||||
You can enable the Editorial Workflow with the following line in your Simple CMS `config.yml` file:
|
||||
|
||||
```yaml
|
||||
publish_mode: editorial_workflow
|
||||
```
|
||||
|
||||
In order to track unpublished entries statuses the GitLab implementation uses merge requests labels and the BitBucket implementation uses pull requests comments.
|
||||
|
||||
## i18n Support
|
||||
|
||||
The CMS can provide a side by side interface for authoring content in multiple languages.
|
||||
@ -224,13 +214,6 @@ backend:
|
||||
# optional, defaults to 'https://gitlab.com/api/graphql'. Can be used to configure a self hosted GitLab instance.
|
||||
graphql_api_root: https://my-self-hosted-gitlab.com/api/graphql
|
||||
```
|
||||
## Open Authoring
|
||||
|
||||
When using the [GitHub backend](/docs/github-backend), you can use Simple CMS to accept contributions from GitHub users without giving them access to your repository. When they make changes in the CMS, the CMS forks your repository for them behind the scenes, and all the changes are made to the fork. When the contributor is ready to submit their changes, they can set their draft as ready for review in the CMS. This triggers a pull request to your repository, which you can merge using the GitHub UI.
|
||||
|
||||
At the same time, any contributors who *do* have write access to the repository can continue to use Simple CMS normally.
|
||||
|
||||
More details and setup instructions can be found on [the Open Authoring docs page](/docs/open-authoring).
|
||||
|
||||
## Folder Collections Path
|
||||
|
||||
@ -473,19 +456,6 @@ import styles from '!css-loader!sass-loader!../main.scss';
|
||||
CMS.registerPreviewStyle(styles.toString(), { raw: true });
|
||||
```
|
||||
|
||||
## Squash merge GitHub pull requests
|
||||
|
||||
When using the [Editorial Workflow](../configuration-options/#publish-mode) with the `github` or GitHub-connected `git-gateway` backends, Simple CMS creates a pull request for each unpublished entry. Every time the unpublished entry is changed and saved, a new commit is added to the pull request. When the entry is published, the pull request is merged, and all of those commits are added to your project commit history in a merge commit.
|
||||
|
||||
The squash merge option causes all commits to be "squashed" into a single commit when the pull request is merged, and the resulting commit is rebased onto the target branch, avoiding the merge commit altogether.
|
||||
|
||||
To enable this feature, you can set the following option in your Simple CMS `config.yml`:
|
||||
|
||||
```yaml
|
||||
backend:
|
||||
squash_merges: true
|
||||
```
|
||||
|
||||
## Commit Message Templates
|
||||
|
||||
You can customize the templates used by Simple CMS to generate commit messages by setting the `commit_messages` option under `backend` in your Simple CMS `config.yml`.
|
||||
@ -502,7 +472,6 @@ backend:
|
||||
delete: Delete {{collection}} “{{slug}}”
|
||||
uploadMedia: Upload “{{path}}”
|
||||
deleteMedia: Delete “{{path}}”
|
||||
openAuthoring: '{{message}}'
|
||||
```
|
||||
|
||||
Simple CMS generates the following commit types:
|
||||
@ -514,7 +483,6 @@ Simple CMS generates the following commit types:
|
||||
| `delete` | An existing entry is deleted | `slug`, `path`, `collection`, `author-login`, `author-name` |
|
||||
| `uploadMedia` | A media file is uploaded | `path`, `author-login`, `author-name` |
|
||||
| `deleteMedia` | A media file is deleted | `path`, `author-login`, `author-name` |
|
||||
| `openAuthoring` | A commit is made via a forked repository | `message`, `author-login`, `author-name` |
|
||||
|
||||
Template tags produce the following output:
|
||||
|
||||
@ -575,7 +543,7 @@ CMS.registerEventListener({
|
||||
});
|
||||
```
|
||||
|
||||
Supported events are `prePublish`, `postPublish`, `preUnpublish`, `postUnpublish`, `preSave` and `postSave`. The `preSave` hook can be used to modify the entry data like so:
|
||||
Supported events are `prePublish`, `postPublish`, `preSave` and `postSave`. The `preSave` hook can be used to modify the entry data like so:
|
||||
|
||||
```javascript
|
||||
CMS.registerEventListener({
|
||||
|
||||
@ -20,7 +20,7 @@ To enable it:
|
||||
|
||||
With Bitbucket's Implicit Grant, users can authenticate with Bitbucket directly from the client. To do this:
|
||||
|
||||
1. Follow the [Atlassian docs](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html) to create an OAuth consumer. Make sure you allow `Account/Read` and `Repository/Write` permissions. To use the [Editorial Workflow](https://www.simplecms.github.io/simple-cms/docs/configuration-options/#publish-mode), allow `PullRequests/Write` permissions. For the **Callback URL**, enter the address where you access Simple CMS, for example, `https://www.mysite.com/admin/`.
|
||||
1. Follow the [Atlassian docs](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html) to create an OAuth consumer. Make sure you allow `Account/Read` and `Repository/Write` permissions. For the **Callback URL**, enter the address where you access Simple CMS, for example, `https://www.mysite.com/admin/`.
|
||||
2. Bitbucket gives you a **Key**. Copy this Key and enter it in your Simple CMS `config.yml` file, along with the following settings:
|
||||
|
||||
```yaml
|
||||
|
||||
@ -26,29 +26,6 @@ The `backend` option specifies how to access the content for your site, includin
|
||||
|
||||
**Note**: no matter where you access Simple CMS — whether running locally, in a staging environment, or in your published site — it will always fetch and commit files in your hosted repository (for example, on GitHub), on the branch you configured in your Simple CMS config.yml file. This means that content fetched in the admin UI will match the content in the repository, which may be different from your locally running site. It also means that content saved using the admin UI will save directly to the hosted repository, even if you're running the UI locally or in staging. If you want to have your local CMS write to a local repository, try the `local_backend` setting, [currently in beta](/docs/beta-features/#working-with-a-local-git-repository).
|
||||
|
||||
## Publish Mode
|
||||
|
||||
By default, all entries created or edited in the Simple CMS are committed directly into the main repository branch.
|
||||
|
||||
The `publish_mode` option allows you to enable "Editorial Workflow" mode for more control over the content publishing phases. All unpublished entries will be arranged in a board according to their status, and they can be further reviewed and edited before going live.
|
||||
|
||||
**Note:** Editorial workflow works with GitHub repositories, and support for GitLab and Bitbucket is [in beta](/docs/beta-features/#gitlab-and-bitbucket-editorial-workflow-support).
|
||||
|
||||
You can enable the Editorial Workflow with the following line in your Simple CMS `config.yml` file:
|
||||
|
||||
```yaml
|
||||
# /admin/config.yml
|
||||
publish_mode: editorial_workflow
|
||||
```
|
||||
|
||||
From a technical perspective, the workflow translates editor UI actions into common Git commands:
|
||||
|
||||
| Actions in Simple CMS UI | Perform these Git actions |
|
||||
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| Save draft | Commits to a new branch (named according to the pattern `cms/collectionName/entrySlug`), and opens a pull request |
|
||||
| Edit draft | Pushes another commit to the draft branch/pull request |
|
||||
| Approve and publish draft | Merges pull request and deletes branch |
|
||||
|
||||
## Media and Public Folders
|
||||
|
||||
Simple CMS users can upload files to your repository using the Media Gallery. The following settings specify where these files are saved, and where they can be accessed on your built site.
|
||||
@ -148,16 +125,6 @@ When a translation for the selected locale is missing the English one will be us
|
||||
|
||||
> All locales are registered by default (so you only need to update your `config.yml`).
|
||||
|
||||
## Show Preview Links
|
||||
|
||||
[Deploy preview links](../deploy-preview-links) can be disabled by setting `show_preview_links` to `false`.
|
||||
|
||||
**Example:**
|
||||
|
||||
```yaml
|
||||
show_preview_links: false
|
||||
```
|
||||
|
||||
## Search
|
||||
|
||||
The search functionally requires loading all collection(s) entries, which can exhaust rate limits on large repositories.
|
||||
@ -210,7 +177,6 @@ The `collections` setting is the heart of your Simple CMS configuration, as it d
|
||||
* `files` or `folder` (requires one of these): specifies the collection type and location; details in [Collection Types](../collection-types)
|
||||
* `filter`: optional filter for `folder` collections; details in [Collection Types](../collection-types)
|
||||
* `create`: for `folder` collections only; `true` allows users to create new items in the collection; defaults to `false`
|
||||
* `publish`: for `publish_mode: editorial_workflow` only; `false` hides UI publishing controls for a collection; defaults to `true`
|
||||
* `hide`: `true` hides a collection in the CMS UI; defaults to `false`. Useful when using the relation widget to hide referenced collections.
|
||||
* `delete`: `false` prevents users from deleting items in a collection; defaults to `true`
|
||||
* `extension`: see detailed description below
|
||||
@ -297,46 +263,6 @@ slug: "{{year}}-{{month}}-{{day}}_{{title}}_{{some_other_field}}"
|
||||
slug: "{{year}}-{{month}}-{{day}}_{{fields.slug}}"
|
||||
```
|
||||
|
||||
### `preview_path`
|
||||
|
||||
A string representing the path where content in this collection can be found on the live site. This allows deploy preview links to direct to lead to a specific piece of content rather than the site root of a deploy preview.
|
||||
|
||||
**Available template tags:**
|
||||
|
||||
Template tags are the same as those for [slug](#slug), with the following exceptions:
|
||||
|
||||
* `{{slug}}` is the entire slug for the current entry (not just the url-safe identifier, as is the case with [`slug` configuration](#slug))
|
||||
* The date based template tags, such as `{{year}}` and `{{month}}`, are pulled from a date field in your entry, and may require additional configuration - see [`preview_path_date_field`](#preview_path_date_field) for details. If a date template tag is used and no date can be found, `preview_path` will be ignored.
|
||||
* `{{dirname}}` The path to the file's parent directory, relative to the collection's `folder`.
|
||||
* `{{filename}}` The file name without the extension part.
|
||||
* `{{extension}}` The file extension.
|
||||
|
||||
**Examples:**
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
- name: posts
|
||||
preview_path: "blog/{{year}}/{{month}}/{{slug}}"
|
||||
```
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
- name: posts
|
||||
preview_path: "blog/{{year}}/{{month}}/{{filename}}.{{extension}}"
|
||||
```
|
||||
|
||||
### `preview_path_date_field`
|
||||
|
||||
The name of a date field for parsing date-based template tags from `preview_path`. If this field is not provided and `preview_path` contains date-based template tags (eg. `{{year}}`), Simple CMS will attempt to infer a usable date field by checking for common date field names, such as `date`. If you find that you need to specify a date field, you can use `preview_path_date_field` to tell Simple CMS which field to use for preview path template tags.
|
||||
|
||||
**Example:**
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
- name: posts
|
||||
preview_path_date_field: "updated_on"
|
||||
```
|
||||
|
||||
### `fields`
|
||||
|
||||
The `fields` option maps editor UI widgets to field-value pairs in the saved file. The order of the fields in your Simple CMS `config.yml` file determines their order in the editor UI and in the saved file.
|
||||
@ -454,4 +380,4 @@ Defaults to an empty list.
|
||||
pattern: \d{4}
|
||||
- label: Drafts
|
||||
field: draft
|
||||
```
|
||||
```
|
||||
|
||||
@ -1,149 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@ -20,22 +20,6 @@ backend:
|
||||
# branch: main
|
||||
```
|
||||
|
||||
## Specifying a status for deploy previews
|
||||
|
||||
The GitHub backend supports [deploy preview links](../deploy-preview-links). Simple CMS checks the
|
||||
`context` of a commit's [statuses](https://help.github.com/articles/about-status-checks/) and infers
|
||||
one that seems to represent a deploy preview. If you need to customize this behavior, you can
|
||||
specify which context to look for using `preview_context`:
|
||||
|
||||
```yaml
|
||||
backend:
|
||||
name: github
|
||||
repo: my/repo
|
||||
preview_context: my-provider/deployment
|
||||
```
|
||||
|
||||
The above configuration would look for the status who's `"context"` is `"my-provider/deployment"`.
|
||||
|
||||
## Git Large File Storage (LFS)
|
||||
|
||||
Please note that the GitHub backend **does not** support [git-lfs](https://git-lfs.github.com/), see [this issue](https://github.com/SimpleCMS/simple-cms/issues/1206) for more information.
|
||||
|
||||
@ -1,79 +0,0 @@
|
||||
---
|
||||
group: Workflow
|
||||
weight: 20
|
||||
title: Open Authoring
|
||||
---
|
||||
**This is a [beta feature](/docs/beta-features#open-authoring).**
|
||||
|
||||
When using the [GitHub backend](/docs/github-backend), you can use Simple CMS to accept contributions from GitHub users without giving them access to your repository. When they make changes in the CMS, the CMS forks your repository for them behind the scenes, and all the changes are made to the fork. When the contributor is ready to submit their changes, they can set their draft as ready for review in the CMS. This triggers a pull request to your repository, which you can merge using the GitHub UI.
|
||||
|
||||
At the same time, any contributors who *do* have write access to the repository can continue to use Simple CMS normally.
|
||||
|
||||
## Requirements
|
||||
|
||||
* You must use [the GitHub backend](/docs/github-backend).
|
||||
|
||||
**Note that the [Git Gateway backend](/docs/git-gateway-backend/#git-gateway-with-netlify-identity) does *not* support Open Authoring, even when the underlying repo is on GitHub.**
|
||||
* For private GitHub repos the user must have `read` access on the repo, and you must explicitly set the auth_scope to `repo`, for example:
|
||||
|
||||
```yaml
|
||||
backend:
|
||||
name: github
|
||||
repo: owner-name/private-repo-name # path to private repo
|
||||
auth_scope: repo # this is needed to fork the private repo
|
||||
open_authoring: true
|
||||
```
|
||||
|
||||
## Enabling Open Authoring
|
||||
|
||||
1. [Enable the editorial workflow](/docs/configuration-options/#publish-mode) by setting `publish_mode` to `editorial_workflow` in your `config.yml`.
|
||||
2. Set `open_authoring` to `true` in the `backend` section of your `config.yml`, as follows:
|
||||
|
||||
```yaml
|
||||
backend:
|
||||
name: github
|
||||
repo: owner-name/repo-name # Path to your GitHub repository
|
||||
open_authoring: true
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
When a user logs into Simple CMS who doesn't have write access to your repo, the CMS asks for permission to create a fork of your repo (or uses their existing fork, if they already have one). They are then presented with the normal CMS interface. The published content shown is from the original repo, so it stays up-to-date as changes are made.
|
||||
|
||||
On the editorial workflow screen, the normal three columns are replaced by two columns instead — "Draft" and "Ready to Review".
|
||||
|
||||
When they make changes to content in the CMS, the changes are made to a branch on their fork. In the editorial workflow screen, they see only their own pending changes. Once they're ready to submit their changes, they can move the card into the "Ready To Review" column to create a pull request. When the pull request is merged (by a repository maintainer via the GitHub UI), Simple CMS deletes the branch and removes the card from the user's editorial workflow screen. Open Authoring users cannot publish entries through the CMS.
|
||||
|
||||
Users who *do* have write access to the original repository continue to use the CMS normally. Unpublished changes made by users via Open Authoring are not visible on the editorial workflow screen, and their unpublished changes must be merged through the GitHub UI.
|
||||
|
||||
## Alternative for external contributors with Git Gateway
|
||||
|
||||
[As noted above](#requirements), Open Authoring does not work with the Git Gateway backend. However, you can use Git Gateway on a site with Netlify Identity that has [open registration](https://www.netlify.com/docs/identity/#adding-identity-users). This lets users create accounts on your site and log into the CMS. There are a few differences, including the following:
|
||||
|
||||
* Users don't need to know about GitHub or create a GitHub account. Instead, they use Netlify Identity accounts that are created on your site and managed by you.
|
||||
* The CMS applies users' changes directly to your repo, not to a fork. (If you use the editorial workflow, you can use features like [GitHub's protected branches](https://help.github.com/en/articles/about-protected-branches) or [Netlify's locked deploys](https://www.netlify.com/docs/locked-deploys/) to prevent users from publishing directly to your site from the CMS.)
|
||||
* There is no distinction between users with write access to the repo and users without — all editorial workflow entries are visible from within the CMS and can be published with the CMS. (Unpublished Open Authoring entries, on the other hand, are visible only to the author in the CMS UI or publicly as GitHub PRs.)
|
||||
|
||||
## Linking to specific entries in the CMS
|
||||
|
||||
Open authoring often includes some sort of "Edit this page" link on the live site. Simple CMS supports this via the **edit** path:
|
||||
|
||||
```js
|
||||
/#/edit/{collectionName}/{entryName}
|
||||
```
|
||||
|
||||
For the entry named "general" in the "settings" file collection
|
||||
|
||||
```html
|
||||
https://www.example.com/path-to-cms/#/edit/settings/general
|
||||
```
|
||||
|
||||
For blog post "test.md" in the "posts" folder collection
|
||||
|
||||
```html
|
||||
https://www.example.com/path-to-cms/#/edit/posts/test
|
||||
```
|
||||
|
||||
* **`collectionName`**: the name of the collection as entered in the CMS config.
|
||||
* **`entryName`** *(for [file collections](/docs/collection-types/#file-collections)*: the `name` of the entry from the CMS config.
|
||||
* **`entryName`** *(for [folder collections](/docs/collection-types/#folder-collections)*: the filename, sans extension (the slug).
|
||||
@ -23,7 +23,7 @@ Once you've gotten the hang of it, you can use the file to build whatever collec
|
||||
|
||||
### Render the content provided by Simple CMS as web pages
|
||||
|
||||
Simple CMS manages your content, and provides editorial and admin features, but it doesn't deliver content. It only makes your content available through an API.
|
||||
Simple CMS manages your content, and provides admin features, but it doesn't deliver content. It only makes your content available through an API.
|
||||
|
||||
It is up to developers to determine how to build the raw content into something useful and delightful on the frontend.
|
||||
|
||||
|
||||
@ -111,7 +111,7 @@ _____
|
||||
|
||||
For field values of type string or integer, use normal style without quotation marks.
|
||||
|
||||
Do: Set the value of `publish_mode` to editorial_workflow.
|
||||
Do: Set the value of `imagePullPolicy` to Always.
|
||||
|
||||
Don't: Set the value of `imagePullPolicy` to "Always".
|
||||
_____
|
||||
|
||||
Reference in New Issue
Block a user