Manual GitHub setup guide

docs/src/content/navigation.yaml

@@ -5,13 +5,18 @@ navGroups:
         link:
           discriminant: page
           value: introduction
-      - link:
+      - label: Quick start
+        link:
           discriminant: page
           value: quick-start
-      - label: Automated setup
+      - label: Connect to GitHub with Vercel
+        link:
+          discriminant: page
+          value: connect-to-github-with-vercel
+      - label: Connect to GitHub
         link:
           discriminant: page
-          value: automated-setup-with-template
+          value: connect-to-github
   - groupName: Integration guides
     items:
       - label: Astro

docs/src/content/pages/automated-setup-with-template.mdoc → docs/src/content/pages/connect-to-github-with-vercel.mdoc

@@ -1,5 +1,5 @@
 ---
-title: Automated setup (with template)
+title: Connect to GitHub with Vercel
 ---
 {% aside icon="⚡️" %}
 **TL:DR**
@@ -11,7 +11,7 @@ To use it, you need:
 - A **GitHub repository** for your project
 - A **custom GitHub App** that is allowed to access your project repo
 
-You *can* do that manually… but we’ve created a little semi-automated onboarding process. It turns a lengthy manual setup into a series of… *button clicks* ✨
+You *can* [do that manually](/docs/connect-to-github)… but we’ve created a little semi-automated onboarding process. It turns a lengthy manual setup into a series of… *button clicks* ✨
 {% /aside %}
 
 You’ll be prompted to go through a few steps. You can read the **step by step walkthrough** below for details, but here’s a visual representation of the *mostly automated* journey you’ll be taken on:
@@ -93,7 +93,7 @@ Aaaaannnnd… Here comes Keystatic! ✨
 
 At this point, you’re all setup with a fully deployed project using Keystatic. You can start creating, editing and deleting content.
 
-## Remote setup
+## Local setup
 
 Chances are you want to work on your project locally though. Let’s get you setup on your machine.
 

docs/src/content/pages/connect-to-github.mdoc

@@ -0,0 +1,128 @@
+---
+title: Connect to GitHub
+---
+{% aside icon="⚡️" %}
+**TL:DR**
+
+This guide walks you through the steps of manually connecting your existing Keystatic project to GitHub.
+
+It makes the assumption that you already have:
+
+- An existing **GitHub repository**
+- Keystatic working in `local` mode
+{% /aside %}
+
+If you need an example repo to follow along, you can clone the [Keystatic Manual GitHub Setup Demo](https://github.com/Thinkmill/keystatic-manual-setup-demo) repo.
+
+## Local setup
+
+Let's start by connecting your Keystatic **local project** with GitHub, first.
+
+### Switch to GitHub storage kind
+
+Assuming your Keystatic project is currently setup with `local` mode, the `storage` key in your config looks like this:
+
+```typescript
+storage: {
+  kind: 'local',
+}
+```
+
+Let's change this to use the `github` kind instead.
+
+This expects a `repo` object with keys for the repo `owner` and `name`:
+
+```diff
+storage: {
+-  kind: 'local',
++  kind: 'github',
++  repo: {
++    owner: REPO_OWNER,
++    name: REPO_NAME
++  }   
+}
+```
+
+Make sure the repo `owner` and `name` values match an existing GitHub repository. You can store these values in your `.env` file, or directly inline them in the config — up to you!
+
+### Log in with GitHub
+
+Next time you visit a `/keystatic` route in your browser, you will be prompted to login with GitHub:
+
+{% cloud-image
+   href="https://keystatic.io/images/keystatic-docs/github-login.png"
+   alt="Screenshot of the Login with GitHub button"
+   height="318"
+   width="638" /%}
+
+### Keystatic setup
+
+Since the project is not connected yet, clicking on the login button should redirect you to a `/keystatic/setup` page:
+
+{% cloud-image
+   href="https://keystatic.io/images/keystatic-docs/keystatic-setup.png"
+   alt="Screenshot of Keystatic App setup"
+   height="1480"
+   width="1468" /%}
+
+If you happen to know the URL of your deployed project and/or the GitHub repo is owned by a GitHub organization, you can fill in those fields.
+
+Otherwise, leave them blank and click on "Create GitHub App".
+
+### Create  a custom GitHub App
+
+This will take you to GitHub and prompt you to give a name for your custom GitHub App:
+
+{% cloud-image
+   href="https://keystatic.io/images/keystatic-docs/github-app-creation.png"
+   alt="Screenshot of GitHub's New App creation UI"
+   height="550"
+   width="1210" /%}
+
+### Grant repo access
+
+When the custom App is created, you'll need to install it and give it access to your GitHub repo:
+
+{% cloud-image
+   href="https://keystatic.io/images/keystatic-docs/keystatic-installed.png"
+   alt="Screenshot of successful Keystatic App installation"
+   height="666"
+   width="892" /%}
+
+{% cloud-image
+   href="https://keystatic.io/images/keystatic-docs/authorize-app.png"
+   alt="Screenshot of GitHub custom app authorization UI"
+   height="1902"
+   width="1348" /%}
+
+After that, you'll be taken back to your local Keystatic Admin UI. But this time, you should see references to your GitHub repo and branches! 🎉
+
+{% cloud-image
+   href="https://keystatic.io/images/keystatic-docs/keystatic-branch-ui.png"
+   alt="Screenshot of Keystatic's Admin UI for branch dropdown"
+   height="250"
+   width="672" /%}
+
+### Environment variables
+
+How is Keystatic now connected to our GitHub repo?
+
+The answer lies in the `.env` file of your project:
+
+```bash
+# Keystatic
+KEYSTATIC_GITHUB_CLIENT_ID=...
+KEYSTATIC_GITHUB_CLIENT_SECRET=...
+KEYSTATIC_SECRET=...
+NEXT_PUBLIC_KEYSTATIC_GITHUB_APP_SLUG=...
+```
+
+Besides creating a custom GitHub app, the setup process has also generated **environment variables** used to authenticate users with GitHub, based on their access to the GitHub repo specified in your config's `storage.repo` settings.
+
+If the user has `write` access to the repo, they'll be able to access `/keystatic` routes 👍
+
+---
+
+## Remote setup
+
+// TODO