docs: split and expand backend docs (#3350)

website/content/docs/backends-overview.md

@@ -0,0 +1,24 @@
+---
+title: Overview
+weight: 1
+group: backends
+---
+
+A backend is JavaScript code that allows Netlify CMS to communicate with a service that stores content - typically a Git host like GitHub or GitLab. It provides functions that Netlify CMS can use to do things like read and update files using API's provided by the service.
+
+## Backend Configuration
+
+Individual backends should provide their own configuration documentation, but there are some configuration options that are common to multiple backends. A full reference is below. Note that these are properties of the `backend` field, and should be nested under that field.
+
+| Field           | Default                                                        | Description                                                                                                                                          |
+| --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `repo`          | none                                                           | **Required** for `github`, `gitlab`, and `bitbucket` backends; ignored by `git-gateway`. Follows the pattern `[org-or-username]/[repo-name]`.                                    |
+| `branch`        | `master`                                                       | The branch where published content is stored. All CMS commits and PRs are made to this branch.                                                       |
+| `api_root`      | `https://api.github.com` (GitHub), `https://gitlab.com/api/v4` (GitLab), or `https://api.bitbucket.org/2.0` (Bitbucket)  | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise or self-hosted GitLab.                                                                      |
+| `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.                                                                                  |
+
+## Creating a New Backend
+
+Anyone can write a backend, but we don't yet have a finalized and documented API. If you would like to write your own backend for a service that does not have one currently, we recommend using the [GitHub backend](https://github.com/netlify/netlify-cms/tree/master/packages/netlify-cms-backend-github) as a reference for API and best practices.

website/content/docs/bitbucket-backend.md

@@ -0,0 +1,36 @@
+---
+title: Bitbucket
+weight: 20
+group: backends
+---
+
+For repositories stored on Bitbucket, the `bitbucket` backend allows CMS users to log in directly with their Bitbucket account. Note that all users must have write access to your content repository for this to work.
+
+To enable it:
+
+1. Follow the authentication provider setup steps in the [Netlify docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider).
+2. Add the following lines to your Netlify CMS `config.yml` file:
+
+    ```yaml
+    backend:
+      name: bitbucket
+      repo: owner-name/repo-name # Path to your Bitbucket repository
+    ```
+
+### Client-Side Implicit Grant (Bitbucket)
+
+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. For the **Callback URL**, enter the address where you access Netlify CMS, for example, `https://www.mysite.com/admin/`.
+2. Bitbucket gives you a **Key**. Copy this Key and enter it in your Netlify CMS `config.yml` file, along with the following settings:
+
+    ```yaml
+    backend:
+      name: bitbucket
+      repo: owner-name/repo-name
+      branch: default
+      auth_type: implicit
+      app_id: # The Key from your Bitbucket settings
+    ```
+
+**Warning:** With Bitbucket implicit grant, the authentication is valid for 1 hour only. After that, the user has to login again, **which can lead to data loss** if the expiration occurs while content is being edited.