Reorganize Backends

content/docs/azure-backend.md

@@ -1,6 +1,6 @@
 ---
 group: Accounts
-weight: 20
+weight: 40
 title: Azure
 ---
 

content/docs/basic-steps.md

@@ -4,29 +4,29 @@ group: Add
 weight: 1
 ---
 
-This tutorial guides you through the steps for adding Decap CMS to a site that's built with a common [static site generator](https://www.staticgen.com/), like Jekyll, Hugo, Hexo, or Gatsby.
+This tutorial guides you through the steps for adding Decap CMS to a site that's built with a common [site generator](https://www.staticgen.com/), like Hugo, Jekyll, Hexo, or Gatsby.
 Alternatively, you can [start from a template](/docs/start-with-a-template) or dive right into [configuration options](/docs/configuration-options). The process for adding Decap CMS to a static site can be divided into four main steps:
 
-**1. Install Decap CMS**
+## 1. Install Decap CMS
 
-This is a single page app available at the `/admin` route of your website.
-Check out the [general overview](/docs/intro/) to see what the installation process entails.
+Add 2 files to the `/admin` route of your website.
+Check out the [installation instructions](/docs/install-decap-cms/) to see what the installation process entails.
 
-**2. Choosing a Backend**
+## 2. Choose a Backend
 
-The most common backends are GitHub, GitLab, Bitbucket, and Azure. The backend serves two purpose: Secure access to your website's Decap CMS and allows it to read and update content files in your git repo. More information about configuring the backend can be found [here](/docs/backends-overview/).
+The most common backends are Git Gateway, GitHub, GitLab, Bitbucket, and Azure. The backend serves two purposes: Secure access to your website's Decap CMS and allows it to read and update content files in your git repo. More information about configuring the backend can be found [here](/docs/backends-overview/).
 
 If you are experimenting with Decap CMS or developing, you can connect to it via a [local Git repository instead](/docs/working-with-a-local-git-repository/) of a remote backend.
 
-**3. Configure Decap CMS**
+## 3. Configure Decap CMS
 
 The basic configuration includes required information like Git backend provider, branch, and collections to save files to.
 It is recommended to start simple as possible. Once you've gotten the hang of it, you can edit your `config.yml` file to
 build whatever collections and content modeling you want.
 
 Check out the [Configuration Options](/docs/configuration-options/) page for full details about all available options.
 
-**4. Access Your Content**
+## 4. Login to Your CMS
 
 Decap CMS manages your content and provides editorial and admin features via a webpage in a browser, but it doesn't deliver content. Decap CMS 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 within your static site generator.
 

content/docs/bitbucket-backend.md

@@ -1,6 +1,6 @@
 ---
 group: Accounts
-weight: 20
+weight: 30
 title: Bitbucket
 ---
 

content/docs/choose-a-backend.md

@@ -0,0 +1,28 @@
+---
+group: Add
+weight: 3
+title: 2. Choose a Backend
+---
+
+Now that you have your Decap CMS files in place and configured, we have to enable authentication. We will achieve this by connecting to a backend service that will handle user authentication and connecting to repository API. Choose one of the backend options supported by Decap:
+
+- [Git Gateway](/docs/git-gateway-backend)
+- [GitHub](/docs/github-backend)
+- [GitLab](/docs/gitlab-backend)
+- [Bitbucket](/docs/bitbucket-backend)
+- [Azure](/docs/azure-backend)
+- [Gitea](/docs/gitea-backend)
+- [Local Git Repository](/docs/working-with-a-local-git-repository)
+
+If you would like to facilitate your own OAuth authentication rather than use Netlify's service or a client side flow like implicit or PKCE, you can use one of the community-maintained projects from the [External OAuth Clients](/docs/external-oauth-clients) list.
+
+<nav class="pagination-nav">
+  <a href="/docs/install-decap-cms/" class="button">
+    <div class="pagination-nav__sublabel">Previous</div>
+    <div class="pagination-nav__label">1. Install Decap CMS</div>
+  </a>
+  <a href="/docs/login-to-your-cms/" class="button pagination-nav__next">
+    <div class="pagination-nav__sublabel">Next</div>
+    <div class="pagination-nav__label">3. Configure Decap CMS</div>
+  </a>
+</nav>

content/docs/configure-decap-cms.md

@@ -8,19 +8,15 @@ Configuration is different for every site, so we'll break it down into parts. Ad
 
 ### Backend
 
-We're using [Netlify](https://www.netlify.com) for our hosting and authentication in this tutorial, so backend configuration is fairly straightforward.
-
-For GitHub and GitLab repositories, you can start your Decap CMS `config.yml` file with these lines:
+We covered this in [Choose a Backend](/docs/choose-a-backend/) but here's a quick reminder. If you're using GitHub, your `config.yml` file should look like this:
 
 ```yaml
 backend:
-  name: git-gateway
+  name: github
   branch: main # Branch to update (optional; defaults to master)
 ```
 
-_(For Bitbucket repositories, use the [Bitbucket backend](/docs/bitbucket-backend) instructions instead.)_
-
-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`.
+The configuration above specifies your backend protocol and your publication branch. If you leave out the `branch` declaration, it defaults to `master`.
 
 ### Media and Public Folders
 
@@ -139,12 +135,12 @@ collections:
 ```
 
 <nav class="pagination-nav">
-  <a href="/docs/choosing-a-backend/" class="button">
+  <a href="/docs/choose-a-backend/" class="button">
     <div class="pagination-nav__sublabel">Previous</div>
-    <div class="pagination-nav__label">2. Choosing A Backend</div>
+    <div class="pagination-nav__label">2. Choose A Backend</div>
   </a>
-  <a href="/docs/access-your-content/" class="button pagination-nav__next">
+  <a href="/docs/login-to-your-cms/" class="button pagination-nav__next">
     <div class="pagination-nav__sublabel">Next</div>
-    <div class="pagination-nav__label">4. Access Your Content</div>
+    <div class="pagination-nav__label">4. Login to Your CMS</div>
   </a>
 </nav>

content/docs/external-oauth-clients.md

@@ -1,6 +1,6 @@
 ---
 group: Accounts
-weight: 60
+weight: 65
 title: External OAuth Clients
 ---
 If you would like to facilitate your own OAuth authentication rather than use Netlify's service or a client side flow like implicit or PKCE, you can use one of the community-maintained projects below. Feel free to hit the "Edit this page" button if you'd like to add yours!

content/docs/git-gateway-backend.md

@@ -1,25 +1,72 @@
 ---
 title: Git Gateway
-weight: 10
+weight: 5
 group: Accounts
 ---
-
 [Git Gateway](https://github.com/netlify/git-gateway) is a Netlify open source project that allows you to add editors to your site CMS without giving them direct write access to your GitHub or GitLab repository. (For Bitbucket repositories, use the [Bitbucket backend](../bitbucket-backend/) instead.)
 
-## Git Gateway with Netlify
+## Setup on Netlify
+
+Netlify offers a built-in authentication service called [Identity](https://docs.netlify.com/security/secure-access-to-sites/identity/). In order to use it, connect your site repo with Netlify. Netlify has published a general [Step-by-Step Guide](https://www.netlify.com/blog/2016/10/27/a-step-by-step-guide-deploying-a-static-site-or-single-page-app/) for this, along with detailed guides for many popular static site generators.
 
-The [Netlify Identity](https://www.netlify.com/docs/identity/) service can handle the authentication and provides a simple interface for user management. The Decap CMS [featured templates](../start-with-a-template) are working examples of this backend.
+### Enable Identity and Git Gateway
 
-To use it in your own project stored on GitHub or GitLab, follow these steps:
+Netlify's Identity and Git Gateway services allow you to manage CMS admin users for your site without requiring them to have an account with your Git host or commit access on your repo. From your site dashboard on Netlify:
 
-1. Head over to the [Netlify Identity docs](https://www.netlify.com/docs/identity) and follow the steps to get started.
-2. Add the following lines to your Decap CMS `config.yml` file:
+1. Go to **Integrations > Identity > Netlify Identity - Enable**, click **Enable Identity**, and go to **Configuration and usage**. 
+2. Under **Registration**, select **Open** or **Invite only**. In most cases, you want only invited users to access your CMS, but if you're just experimenting, you can leave it open for convenience.
+3. If you'd like to allow one-click login with services like Google and GitHub, check the boxes next to the services you'd like to use, under **External providers**.
+4. Scroll down to **Services > Git Gateway**, and click **Enable Git Gateway**. This authenticates with your Git host and generates an API access token. In this case, we're leaving the **Roles** field blank, which means any logged in user may access the CMS. For information on changing this, check the [Netlify Identity documentation](https://www.netlify.com/docs/identity/).
+5. Add the following lines to your Decap CMS `config.yml` file:
 
 ```yaml
 backend:
   name: git-gateway
 ```
 
+## Add the Netlify Identity Widget
+With the backend configured to handle authentication, now you need a frontend interface to connect to it. The open source Netlify Identity Widget is a drop-in widget made for just this purpose. To include the widget in your site, add the following script tag in one or two places, depending on the method you choose for user registration:
+
+```html
+<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
+```
+
+### Site-wide registration
+
+Add the script to the `<head>` of your CMS index page at `/admin/index.html`, as well as the `<head>` of your site's main index page. Depending on how your site generator is set up, this may mean you need to add it to the default template, or to a "partial" or "include" template. If you can find where the site stylesheet is linked, that's probably the right place. Alternatively, you can include the script in your site using Netlify's [Script Injection](https://www.netlify.com/docs/inject-analytics-snippets/) feature.
+
+When a user logs in with the Netlify Identity widget, an access token directs to the site homepage. In order to complete the login and get back to the CMS, redirect the user back to the `/admin/` path. To do this, add the following script before the closing `body` tag of your site's main index page:
+
+```html
+<script>
+  if (window.netlifyIdentity) {
+    window.netlifyIdentity.on("init", (user) => {
+      if (!user) {
+        window.netlifyIdentity.on("login", () => {
+          document.location.href = "/admin/";
+        });
+      }
+    });
+  }
+</script>
+```
+
+### Admin-only registration
+
+If you use the invite-only registration, you don't need to add the identity widget to the index page. Instead, you can invite users from the Netlify dashboard. To make this work you have to update email tempalates in the Netlify dashboard. Follow [this guide](https://docs.netlify.com/security/secure-access-to-sites/identity/identity-generated-emails/) to learn how to do it. The important part is to change the URLs from `{{ siteURL }}/#...` to `{{ siteURL }}/admin/#...`. That way all links in emails will point to the CMS page, which includes the identity widget. This method is good for performance of your frontend, because it doesn't load the identity widget on the main page.
+
+<nav class="pagination-nav">
+ <a href="/docs/install-decap-cms/" class="button">
+    <div class="pagination-nav__sublabel">Previous</div>
+    <div class="pagination-nav__label">1. Install Decap CMS</div>
+  </a>
+   <a href="/docs/configure-decap-cms/" class="button pagination-nav__next">
+    <div class="pagination-nav__sublabel">Next</div>
+    <div class="pagination-nav__label">3. Configure Decap CMS</div>
+  </a>
+</nav>
+
+
 ## Reconnect after Changing Repository Permissions
 
 If you change ownership on your repository, or convert a repository from public to private, you may need to reconnect Git Gateway with proper permissions. Find further instructions in the [Netlify Git Gateway docs](https://www.netlify.com/docs/git-gateway/#reconnect-after-changing-repository-permissions).

content/docs/gitea-backend.md

@@ -1,7 +1,7 @@
 ---
 title: Gitea / Forgejo
 group: Accounts
-weight: 25
+weight: 50
 ---
 
 For repositories stored on [Gitea](https://gitea.com) or [Forgejo](https://forgejo.org) instances, the `gitea` backend allows CMS users to log in directly with their Gitea/Forgejo account. Note that all users must have push access to your content repository for this to work.