Docs: adds mkdocs features, adds theming (#728)

* Add stylesheet & mkdocs features

- Adds a custom stylesheet & brand colours
- Adds Recursive as the code font
- Adds repo info to the nav bar
- Adds auto tracking ID links for deep linking to sections as users scroll the page
- Index pages are now a part of their section as determined by their H1
- Removes mkdocs info from future footer

* Reorganize content

- Renames "Dev" to "Develop" for improved navigation labels
- 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

* Rename "Developer Docs" index page

- Better title for sidebar

* Update docs.md

- Adds links to tools
- Adds future docs style guide section
- Updates name and makes it an H1

- Replaces hyphens on the homepage with em dashes

* deployment index page: changed title, removed non-k8s section, cleaned up intro
* develop index page: changed title
fixed typo on main page

---------

Co-authored-by: Ilya Kreymer <ikreymer@gmail.com>

docs/deploy/index.md

@@ -1,21 +1,15 @@
-# Introduction
+# Deploying Browsertrix Cloud
 
 Browsertrix Cloud is designed to be a cloud-native application running in Kubernetes.
 
-However, despite the name, it is perfectly reasonable (and easy!) to deploy Browsertrix Cloud locally using one of the many available local Kubernetes options. Here are a few recommendations for different scenarios.
+However, despite the name, it is perfectly reasonable (and easy!) to deploy Browsertrix Cloud locally using one of the many available local Kubernetes options.
 
 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.
-
-### Non Kubernetes Deployments
-
-Previously, Browsertrix Cloud also supported Docker Compose and podman-based deployment. This is now deprecated due to the complexity
-of maintaining feature parity across different setups, and with various Kubernetes deployment options being available and easy to deploy, even on a single machine.
-
-Making deployment of Browsertrix Cloud as easy as possible remains a key goal, and we welcome suggestions for how we can further improve our Kubernetes deployment options.
 
+We have prepared a [Local Deployment Guide](./local) which covers several options for testing Browsertrix Cloud locally on a single machine,
+as well as a [Production (Self-Hosted and Cloud) Deployment](./production) guides to help with
+setting up Browsertrix Cloud for different production scenarios.

docs/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
     ```

docs/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:

docs/dev/docs.md

@@ -1,16 +0,0 @@
-## Updating the Docs
-
-This documentation is built with MkDocs and configured via `mkdocs.yml` in the project root.
-
-The docs can be found in the `./docs` subdirectory.
-
-To build this documentation locally, install Material for MkDocs with pip:
-
-```shell
-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)

docs/develop/docs.md

@@ -0,0 +1,19 @@
+# Writing documentation
+
+Our documentation is built with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) and configured via `mkdocs.yml` in the project root.
+
+The docs can be found in the `./docs` subdirectory.
+
+To build the docs locally, install Material for MkDocs with pip:
+
+```shell
+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)
+
+## Docs style guide
+
+TODO!

docs/develop/index.md

@@ -1,4 +1,4 @@
-# Developer Docs
+# Developing Browsertrix Cloud
 
 Browsertrix Cloud consists of a Python-based backend and TypeScript-based frontend.
 

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.
+- [Deployment Guide](./deploy) — How to install and deploy Browsertrix Cloud on your local machine, or in the cloud.
+- [Developer Docs](./develop) — Information on developing Browsertrix Cloud itself.
+- [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!
 

docs/stylesheets/extra.css

@@ -0,0 +1,22 @@
+/* :root {
+    --color-wr-lightred: #E3353F;
+    --color-wr-darkred: #A2001D;
+} */
+
+
+/* Import monospaced recursive from Google Fonts */
+@import url('https://fonts.googleapis.com/css2?family=Recursive:MONO@1&display=swap');
+
+
+[data-md-color-scheme="webrecorder"] {
+    --md-primary-fg-color: #008873;
+    --md-primary-fg-color--light: #008873;
+    --md-primary-fg-color--dark: #003c32;
+    --md-primary-bg-color--light: #FFF;
+    --md-accent-fg-color: #01b297;
+
+    /* Typography Color Scheme */
+    --md-typeset-color: #003c32;
+    --md-typeset-a-color: #008873;
+    
+  }

mkdocs.yml

@@ -1,4 +1,9 @@
 site_name: Browsertrix Cloud Docs
+repo_url: https://github.com/webrecorder/browsertrix-cloud/
+repo_name: Browsertrix Cloud
+edit_uri: edit/main/docs/
+extra_css:
+    - stylesheets/extra.css
 theme:
   name: material
   features:
@@ -6,12 +11,13 @@ theme:
     - navigation.tabs
     - navigation.tabs.sticky
     - navigation.instant
+    - navigation.tracking
+    - navigation-indexes
   font:
     text: Inter
     code: Recursive
   palette:
-    primary: teal
-    accent: cyan
+    scheme: webrecorder
   logo: assets/brand/btrix-logo.svg
 
   icon:
@@ -30,3 +36,5 @@ markdown_extensions:
   - pymdownx.details
   - pymdownx.superfences
 
+extra:
+  generator: false