From f6bab4f26c7b403bd2de55c9562c15edba19eb10 Mon Sep 17 00:00:00 2001
From: Henry Wilkinson <henry@wilkinson.graphics>
Date: Mon, 27 Mar 2023 02:11:41 -0400
Subject: [PATCH] Reorganize content
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Renames "Dev" to "Develop" for improved navigation labels
- Deployment docs are now located under a larger "Development" section (fewer nav bar choices & realistically I think anyone who wants to do one is going to be referring to the other)
- Adds links to tools the first time they're mentioned
- Rewords part of the homepage
- Hides section navigation on the homepage (now we don't have a blank section nav bar!
- Adds some syntax highlighting
- Removes some manual word wrapping — this was done very rarely / inconsistently
---
 .../deploy/ansible/digitalocean.md            |  0
 docs/{ => develop}/deploy/ansible/microk8s.md |  0
 docs/{ => develop}/deploy/index.md            |  4 +--
 docs/{ => develop}/deploy/local.md            | 25 +++++++++----------
 docs/{ => develop}/deploy/production.md       | 11 ++++----
 docs/{dev => develop}/docs.md                 |  3 +--
 docs/{dev => develop}/frontend-dev.md         |  0
 docs/{dev => develop}/index.md                |  0
 docs/index.md                                 | 16 ++++++++----
 9 files changed, 31 insertions(+), 28 deletions(-)
 rename docs/{ => develop}/deploy/ansible/digitalocean.md (100%)
 rename docs/{ => develop}/deploy/ansible/microk8s.md (100%)
 rename docs/{ => develop}/deploy/index.md (92%)
 rename docs/{ => develop}/deploy/local.md (95%)
 rename docs/{ => develop}/deploy/production.md (93%)
 rename docs/{dev => develop}/docs.md (75%)
 rename docs/{dev => develop}/frontend-dev.md (100%)
 rename docs/{dev => develop}/index.md (100%)

diff --git a/docs/deploy/ansible/digitalocean.md b/docs/develop/deploy/ansible/digitalocean.md
similarity index 100%
rename from docs/deploy/ansible/digitalocean.md
rename to docs/develop/deploy/ansible/digitalocean.md
diff --git a/docs/deploy/ansible/microk8s.md b/docs/develop/deploy/ansible/microk8s.md
similarity index 100%
rename from docs/deploy/ansible/microk8s.md
rename to docs/develop/deploy/ansible/microk8s.md
diff --git a/docs/deploy/index.md b/docs/develop/deploy/index.md
similarity index 92%
rename from docs/deploy/index.md
rename to docs/develop/deploy/index.md
index ea41370d..53e1addf 100644
--- a/docs/deploy/index.md
+++ b/docs/develop/deploy/index.md
@@ -1,4 +1,4 @@
-# Introduction
+# Introduction to Deployment
 
 Browsertrix Cloud is designed to be a cloud-native application running in Kubernetes.
 
@@ -7,7 +7,7 @@ However, despite the name, it is perfectly reasonable (and easy!) to deploy Brow
 The main requirements for Browsertrix Cloud are:
 
 - A Kubernetes Cluster
-- Helm 3 (package manager for Kubernetes)
+- [Helm 3](https://helm.sh/) (package manager for Kubernetes)
 
 We have prepared a [Local Deployment](./local) and [Production (Self-Hosted and Cloud) Deployment](./production) guides to help with
 setting up Browsertrix Cloud for different scenarios.
diff --git a/docs/deploy/local.md b/docs/develop/deploy/local.md
similarity index 95%
rename from docs/deploy/local.md
rename to docs/develop/deploy/local.md
index 273cc913..78df912b 100644
--- a/docs/deploy/local.md
+++ b/docs/develop/deploy/local.md
@@ -4,13 +4,11 @@ To just test out Browsertrix Cloud on your local machine, you'll first need to h
 
 ## Installing Kubernetes
 
-Before running Browsertrix Cloud, you'll need to set up a running Kubernetes cluster.
+Before running Browsertrix Cloud, you'll need to set up a running [Kubernetes](https://kubernetes.io/) cluster.
 
 Today, there are numerous ways to deploy Kubernetes fairly easily, and we recommend trying one of the single-node options, which include Docker Desktop, microk8s, minikube and k3s.
 
-The instructions below assume you have cloned
-the [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud) repository locally,
-and have local package managers for your platform (eg. `brew` for Mac, `choco` for Windows, etc...) already installed.
+The instructions below assume you have cloned the [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud) repository locally, and have local package managers for your platform (eg. `brew` for Mac, `choco` for Windows, etc...) already installed.
 
 Here are some environment specific instructions for setting up a local cluster from different Kubernetes vendors:
 
@@ -62,7 +60,7 @@ Here are some environment specific instructions for setting up a local cluster f
 
 Once you have a running Kubernetes cluster with one of the options above, and Helm 3 installed, you can then run from the Browsertrix Cloud repo directory:
 
-```
+```shell
 helm upgrade --install -f ./chart/values.yaml -f ./chart/examples/local-config.yaml btrix ./chart/
 ```
 
@@ -81,7 +79,7 @@ Note that the admin user and password will not be reset after creation.
 
 After running the helm command, you should see something like:
 
-```
+```shell
 Release "btrix" does not exist. Installing it now.
 NAME: btrix
 LAST DEPLOYED: <time>
@@ -117,7 +115,7 @@ The outputs of these commands will be helpful if you'd like to report an issue [
 
 To update the cluster, re-run the same command again, which will pull the latest images. In this way, you can upgrade to the latest release of Browsertrix Cloud. The upgrade will preserve the database and current archives.
 
-```
+```shell
 helm upgrade --install -f ./chart/values.yaml -f ./chart/examples/local-config.yaml btrix ./chart/
 ```
 
@@ -136,7 +134,7 @@ By default, this setup will pull the latest release of Browsertrix Cloud. Howeve
 
 First, open `./chart/examples/local-config.yaml` and add the following, which will ensure only local images are used:
 
-```
+```yaml
 backend_pull_policy: "Never"
 frontend_pull_policy: "Never"
 ```
@@ -157,7 +155,7 @@ Now, rebuild either the backend and/or frontend images locally. The exact proces
 
     2. In `./chart/examples/local-config.yaml`, uncomment out one or both of the following lines to use the local images:
 
-    ```
+    ```yaml
     backend_image: "localhost:32000/webrecorder/browsertrix-backend:latest"
     frontend_image: "localhost:32000/webrecorder/browsertrix-frontend:latest"
     ```
@@ -168,12 +166,13 @@ Now, rebuild either the backend and/or frontend images locally. The exact proces
 
     To build the backend image, run:
 
-    ```
+    ```shell
     minikube image build -t webrecorder/browsertrix-backend:latest ./backend
     ```
 
     To build a local frontend image, run:
-    ```
+    
+    ```shell
     minikube image build -t webrecorder/browsertrix-frontend:latest ./frontend
     ```
 
@@ -185,14 +184,14 @@ Now, rebuild either the backend and/or frontend images locally. The exact proces
 
     2. Serializer the images to .tar:
 
-    ```
+    ```shell
     docker save webrecorder/browsertrix-backend:latest > ./backend.tar
     docker save webrecorder/browsertrix-frontend:latest > ./frontend.tar
     ```
 
     3. Import images into k3s containerd:
 
-    ```
+    ```shell
     k3s ctr images import --base-name webrecorder/browsertrix-backend:latest ./backend.tar
     k3s ctr images import --base-name webrecorder/browsertrix-frontend:latest ./frontend.tar
     ```
diff --git a/docs/deploy/production.md b/docs/develop/deploy/production.md
similarity index 93%
rename from docs/deploy/production.md
rename to docs/develop/deploy/production.md
index 71213652..5631701a 100644
--- a/docs/deploy/production.md
+++ b/docs/develop/deploy/production.md
@@ -10,7 +10,7 @@ The production deployments also allow using an external mongodb server, and/or e
 
 ## Single Machine Deployment with MicroK8S
 
-For a single-machine production deployment, we recommend using microk8s.
+For a single-machine production deployment, we recommend using [MicroK8s](https://microk8s.io/).
 
 1. Install MicroK8S, as suggested in [the local deployment guide](../deploy/local.md) and ensure the `ingress` and `cert-manager` addons are also enabled.
 
@@ -22,7 +22,7 @@ For a single-machine production deployment, we recommend using microk8s.
 
 4. Run with:
 
-   ```
+   ```shell
    helm upgrade --install -f ./chart/values.yaml -f ./chart/my-config.yaml btrix ./chart/
    ```
 
@@ -31,7 +31,7 @@ For a single-machine production deployment, we recommend using microk8s.
 
 If you would like to use existing external storage, such an existing S3-compatible storage, also set the default storage, for example:
 
-```
+```yaml
 minio_local: false
 
 storages:
@@ -49,11 +49,10 @@ Note that this setup is not limited to Amazon S3, but should work with any S3-co
 
 If you would like to use an externally hosted MongoDB, you can add the following config to point to a custom MongoDB instance.
 
-The `db_url` should follow the [MongoDB Connection String Format](https://www.mongodb.com/docs/manual/reference/connection-string/)
-which should include the username and password of the remote instance.
+The `db_url` should follow the [MongoDB Connection String Format](https://www.mongodb.com/docs/manual/reference/connection-string/) which should include the username and password of the remote instance.
 
 
-```
+```yaml
 mongo_local: false
 
 mongo_auth:
diff --git a/docs/dev/docs.md b/docs/develop/docs.md
similarity index 75%
rename from docs/dev/docs.md
rename to docs/develop/docs.md
index d5d17f33..65864224 100644
--- a/docs/dev/docs.md
+++ b/docs/develop/docs.md
@@ -12,5 +12,4 @@ pip install mkdocs-material
 
 In the project root directory run `mkdocs serve` to run a local version of the documentation site.
 
-The docs hosted on [docs.browsertrix.cloud](https://docs.browsertrix.cloud) are created from
-the main branch of [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud)
+The docs hosted on [docs.browsertrix.cloud](https://docs.browsertrix.cloud) are created from the main branch of [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud)
diff --git a/docs/dev/frontend-dev.md b/docs/develop/frontend-dev.md
similarity index 100%
rename from docs/dev/frontend-dev.md
rename to docs/develop/frontend-dev.md
diff --git a/docs/dev/index.md b/docs/develop/index.md
similarity index 100%
rename from docs/dev/index.md
rename to docs/develop/index.md
diff --git a/docs/index.md b/docs/index.md
index 405f7733..3ca08d2d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,12 +1,18 @@
-# Welcome
+---
+hide:
+    - navigation
+    - toc
+---
+
+# Home
 
 Welcome to the Browsertrix Cloud official user guide and developer docs. These docs will contain the following sections.
 
-- [Deployment Guide](./deploy) - Info on how to install and deploy Browsertrix Cloud locally or in the cloud.
-- [Developer Docs](./dev) - for info on how to developing Browsertrix Cloud itself.
-- [User Guide](./user-guide) - for info on how to use Browsertrix Cloud system.
+- [Developer Docs](./develop) - Information on developing Browsertrix Cloud itself.
+    - [Deployment Guide](./develop/deploy) - How to install and deploy Browsertrix Cloud on your local machine, or in the cloud.
+- [User Guide](./user-guide) - Instructions and reference for using Browsertrix Cloud.
 
-If you are unfamiliar with Browsertrix Cloud, please check out [our website](https://browsertrix.cloud) or the main repository at [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud)
+If you are unfamiliar with Browsertrix Cloud, please check out [our website](https://browsertrix.cloud), or the main repository at [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud)
 
 Our docs are still under construction. If you find something missing, chances are we haven't gotten around to writing that part yet. If you find typos or something isn't clear or seems incorrect, please open an [issue](https://github.com/webrecorder/browsertrix-cloud/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) and we'll try to make sure that your questions get answered here in the future!