diff --git a/.github/workflows/mkdocs.yaml b/.github/workflows/mkdocs.yaml
new file mode 100644
index 00000000..78fbaf3b
--- /dev/null
+++ b/.github/workflows/mkdocs.yaml
@@ -0,0 +1,21 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - mkdocs
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: ./mkdocs.yml
\ No newline at end of file
diff --git a/.github/workflows/pygmy.yml b/.github/workflows/pygmy.yml
index d7b79737..d06d2a3c 100644
--- a/.github/workflows/pygmy.yml
+++ b/.github/workflows/pygmy.yml
@@ -250,13 +250,13 @@ jobs:
 
       - name: "[Example] Drupal Postgres"
         run: |
-          cd lagoon-examples/drupal9-postgres;
+          cd lagoon-examples/drupal-postgres;
           docker-compose -p drupal-postgres up -d;
           docker-compose -p drupal-postgres exec -T cli composer install;
-          dockerize -wait http://drupal9-postgres.docker.amazee.io:80 -timeout 10s;
-          curl --HEAD http://drupal9-postgres.docker.amazee.io;
-          curl --HEAD http://drupal9-postgres.docker.amazee.io | grep -i "x-lagoon";
-          ../../pygmy-linux-amd64 status | grep '\- http://drupal9-postgres.docker.amazee.io';
+          dockerize -wait http://drupal-postgres.docker.amazee.io:80 -timeout 10s;
+          curl --HEAD http://drupal-postgres.docker.amazee.io;
+          curl --HEAD http://drupal-postgres.docker.amazee.io | grep -i "x-lagoon";
+          ../../pygmy-linux-amd64 status | grep '\- http://drupal-postgres.docker.amazee.io';
           docker-compose -p drupal-postgres down;
           docker-compose -p drupal-postgres rm;
           cd ../../;
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 00000000..015eb5de
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,19 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+  - requirements: docs/requirements.txt
diff --git a/docs/connect_to_mysql_from_external.md b/docs/connect_to_mysql_from_external.md
index e0da00c7..719b95c0 100644
--- a/docs/connect_to_mysql_from_external.md
+++ b/docs/connect_to_mysql_from_external.md
@@ -11,20 +11,26 @@ Docker assigns a randomly published port for MySQL during each container start.
 
 To get the published port via `docker`:
 
+```
     $ docker port changeme.net.docker.amazee.io
     3306/tcp -> 0.0.0.0:32797
+```
 
 Or via `docker-compose` inside a Drupal repository
 
+```
     $ docker-compose port drupal 3306
     0.0.0.0:32797
+```
 
 ### `linux` Get ip from container
 
 If you are on Linux and run docker native, you also need to get the IP of the container
 
+```
     $ docker inspect --format '{{ .NetworkSettings.IPAddress }}' changeme.net.docker.amazee.io
     172.17.0.4
+```
 
 ### Connect to MySQL
 
diff --git a/docs/drupal_site_containers.md b/docs/drupal_site_containers.md
index a7c498e9..dd7823e2 100644
--- a/docs/drupal_site_containers.md
+++ b/docs/drupal_site_containers.md
@@ -14,14 +14,14 @@ During [Part I](./local_docker_development.md#part-i-shared-docker-containers) w
 
 ##  Find the right `docker-compose.yml`
 
-1. Visit https://github.com/amazeeio/docker or clone https://github.com/amazeeio/docker.git into a folder on your computer
+1. Visit https://github.com/uselagoon/lagoon-examples or clone https://github.com/lagoon-examples/drupal-base.git into a folder on your computer
 2. Copy the desired example file into your Drupal directory (see descriptions below). Use `example-docker-compose-drupal.yml` if unsure.
 3. Rename the file to `docker-compose.yml`
-4. Edit the file according to your needs, change at least the host name. _BTW: It's perfectly fine to commit this file into your git repository, so others that are also using amazee.io docker can use it as well._
+4. Edit the file according to your needs, change at least the host name. _BTW: It's perfectly fine to commit this file into your git repository, so others that are also using docker can use it as well._
 5. Run in the same directory as the `docker-compose.yml`:
 
         docker-compose up -d
-6. If you are on Windows add the URL to the Hosts file (see [windows documentation](local_docker_development/windows.md) for that).
+6. If you are on Windows add the URL to the Hosts file (see [windows documentation](local_docker_development.md) for that).
 7. Open your browser with the entered URL in the `docker-compose.yml`, happy Drupaling!
 
 ## Connect to the container
@@ -78,7 +78,7 @@ When you next start a bash session, you'll be able to use `ddrush` just like you
 
 ## Update Images
 
-We constantly make improvements, updates and some other nice things to our container images. Visit [changelog.amazee.io](https://changelog.amazee.io) to see if there is something new. If you need to update the Docker Images to the newest version from the Docker Hub run in the same folder as the `docker-compose.yml`:
+We constantly make improvements, updates and some other nice things to our container images. Visit the [Lagoon Image releases page](https://github.com/uselagoon/lagoon-images/releases) to see if there is something new. If you need to update the Docker Images to the newest version from the Docker Hub run in the same folder as the `docker-compose.yml`:
 
 	docker-compose pull
 	docker-compose up -d
@@ -92,7 +92,4 @@ Just open another terminal window at the exact same directory than you run the f
 
 ## `docker-compose.yml` example files
 
-| Example File                                                                                                           | PHP    | Services                           | Description                                                                                                                     |
-|----------------------------------------------------------------------------------------------------------------------------------|--------|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
-| [`example-docker-compose-drupal.yml`](https://github.com/amazeeio/docker/blob/master/example-docker-compose-drupal.yml)          | 5.6/7.0/7.1| nginx, varnish, mariadb       |Drupal container without provisions for solr. See comments in file for choosing PHP version and customizing for Composer sites   |
-| [`example-docker-compose-drupal-solr.yml`](https://github.com/amazeeio/docker/blob/master/example-docker-compose-drupal-solr.yml)| 5.6/7.0/7.1| nginx, varnish, mariadb, solr |Drupal container with provisions for solr. See comments in file for choosing PHP version and customizing for Composer sites      |
+Visit https://github.com/uselagoon/lagoon-examples to see a range of example projects that you can clone as a starting point
diff --git a/docs/images/pygmystack_icon.png b/docs/images/pygmystack_icon.png
new file mode 100644
index 00000000..e27fab99
Binary files /dev/null and b/docs/images/pygmystack_icon.png differ
diff --git a/docs/images/pygmystack_icon_wh.png b/docs/images/pygmystack_icon_wh.png
new file mode 100644
index 00000000..52672bb0
Binary files /dev/null and b/docs/images/pygmystack_icon_wh.png differ
diff --git a/docs/images/pygmystack_taglone_col.png b/docs/images/pygmystack_taglone_col.png
new file mode 100644
index 00000000..1a267ef8
Binary files /dev/null and b/docs/images/pygmystack_taglone_col.png differ
diff --git a/docs/index.md b/docs/index.md
index 4a25cefb..60c574e7 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,10 +1,31 @@
-# Pygmy
+# Welcome to pygmystack
 
-`pygmy` is the single tool needed to get the local [amazee.io](https://amazee.io) Docker Drupal Development Environment running on your Linux based system. It built to work with [Docker for Mac](https://docs.docker.com/docker-for-mac/)! (quite a lot for such a [small whale](https://en.wikipedia.org/wiki/Pygmy_sperm_whale) 🐳)
+The pygmy stack is a container stack for local development.
+
+It is a collaboration between:
+
+* [amazee.io](https://www.amazee.io) - Initial development of pygmy, and it's predecessor, [cachalot](https://github.com/amazeeio/cachalot)
+* [@fubarhouse](https://github.com/fubarhouse) - complete rewrite of pygmy in Golang (Thanks Karl!)
+* [the Lagoon team](https://lagoon.sh) - ongoing support and maintenance
+
+Please see [github.com/pygmystack](https://github.com/pygmystack) for more information
+
+**Why use `pygmy`?**
+
+* Starting the necessary Docker Containers for your Docker Development Environment
+The pygmy stack is a container stack for local development, and `pygmy` is the main tool.
+
+It's built to work with:
+
+- [Docker Desktop for Mac](https://docs.docker.com/desktop/mac/)
+- [Docker Desktop for Windows](https://docs.docker.com/desktop/windows/)
+- [Docker Engine for Linux](https://docs.docker.com/engine/)
+
+Quite a lot for such a [small whale](https://en.wikipedia.org/wiki/Pygmy_sperm_whale) 🐳)
 
 **What `pygmy` will handle for you:**
 
-* Starting the necessary Docker Containers for the amazee.io Drupal Docker Development
+* Starting the necessary Docker Containers for local development
 * If on Linux: Adds `nameserver 127.0.0.1` to your `/etc/resolv.conf` file, so that your local Linux can resolve `*.docker.amazee.io` via the dnsmasq container
 * If on Mac with Docker for Mac: Creates the file `/etc/resolver/docker.amazee.io` which tells OS X to forward DNS requests for `*.docker.amazee.io` to the dnsmasq container
 * Tries to add the ssh key in `~/.ssh/id_rsa` to the ssh-agent container (no worries if that is the wrong key, you can add more any time)
diff --git a/docs/installation.md b/docs/installation.md
index 3fd58cb4..37b0e58d 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -8,6 +8,16 @@ Make sure you have the following dependencies installed:
 
 ## Installation
 
+### Installing from homebrew (recommended for most users)
+
+**Works for**: Linux & MacOS
+
+```shell
+brew tap pygmystack/pygmy;
+brew install pygmy;
+```
+
+
 ### Installing from a precompiled binary
 
 Releases on GitHub accompany binaries [available for download](https://github.com/pygmystack/pygmy/releases).
diff --git a/docs/local_docker_development.md b/docs/local_docker_development.md
index 0e4f42b0..c021ddbb 100644
--- a/docs/local_docker_development.md
+++ b/docs/local_docker_development.md
@@ -3,13 +3,13 @@
 
 # Local Drupal Docker Development
 
-amazee.io supports development workflows which involve local development sites. We provide a Drupal Docker development environment that runs on your local computer.
-It uses the exact same configuration for **all** services like on the amazee.io servers. This means:
+Lagoon supports development workflows which involve local development sites. We provide a Drupal Docker development environment that runs on your local computer.
+It uses the exact same configuration for **all** services like on the Lagoon servers. This means:
 
 * If the site runs locally, it also runs on production
 * You can use the exact same `settings.php` file for local and production
 
-**And the best:** You don't need to have any amazee.io account or site running in order to use the local development environment! Just install it, and experience all the benefits of amazee.io for free.
+**And the best:** You don't need to have a Lagoon account or site running in order to use the local development environment! Just install it, and experience all the benefits of Lagoon for free.
 
 The Docker based Drupal Development environment consists of two parts:
 
@@ -23,7 +23,7 @@ The Docker Containers which will run Drupal. These are made to be copied into a
 
 ## What it includes
 
-The amazee.io Local Docker Drupal Development environment equips you with all the tools you need to develop your Drupal site locally:
+An example local Docker Drupal Development environment, such as https://www.github.com/lagoon-examples/drupal-solr, equips you with all the tools you need to develop your Drupal site locally:
 
 * **Webserver:** Nginx
 * **Frontend Caching:** Varnish
@@ -34,7 +34,7 @@ The amazee.io Local Docker Drupal Development environment equips you with all th
 * **Dependency Manager for PHP:** Composer
 * NodeJS / NPM
 
-For more information about software components used in the amazee.io Stack head over to the [Components](../architecture/components.md) overview page.
+For more information about software components used in the Lagoon Stack head over to [their docs](https://docs.lagoon.sh).
 
 ## How this works
 
@@ -50,7 +50,7 @@ It is possible to add mount ssh private keys into Docker containers, but this is
 
 ### The Solution
 
-amazee.io implemented a Drupal Docker Development environment which handles all these issues nicely for you. It allows you to:
+`pygmy` allows you to:
 
 * Access all sites via the Port 80 or 443 with just different URLs like site1.docker.amazee.io and site2.docker.amazee.io
 * Add your SSH Key once to the system and can forget about it, no need to add it to each container
diff --git a/docs/map_addtitional_ports.md b/docs/map_addtitional_ports.md
index fcac2920..50aadf5e 100644
--- a/docs/map_addtitional_ports.md
+++ b/docs/map_addtitional_ports.md
@@ -13,7 +13,7 @@ If you need to map other ports, simply add them to the `ports` section and resta
 
 ### Example for Solr
 
-If you use one of amazee.io Drupal containers with Solr included, your Solr URL most likely looks like this: http://127.0.0.1:8149/solr/drupal/
+If you use one of Lagoon's Drupal containers with Solr included, your Solr URL most likely looks like this: http://127.0.0.1:8149/solr/drupal/
 
 In this case, to play with Solr queries:
 - add `"8149"` to the `ports` section of `docker-compose.yml` file
diff --git a/docs/readthedocs.yml b/docs/readthedocs.yml
deleted file mode 100644
index 768f076d..00000000
--- a/docs/readthedocs.yml
+++ /dev/null
@@ -1 +0,0 @@
-requirements_file: requirements.txt
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 17d39b8a..4c8f017d 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1 +1 @@
-mkdocs>=1
+mkdocs-material
diff --git a/docs/ssh_agent.md b/docs/ssh_agent.md
index d179652c..aed2be19 100644
--- a/docs/ssh_agent.md
+++ b/docs/ssh_agent.md
@@ -2,8 +2,6 @@
 
 Per default your SSH Key at `~/.ssh/id_rsa` is added to the Docker containers from `pygmy`
 
-If you need another key, read the documentation of [`pygmy`](linux_pygmy.md) about this.
-
 ## How it works
 1. `pygmy` starts `amazeeio/ssh-agent` container with a volume `/tmp/amazeeio_ssh-agent`
 2. `pygmy` adds a default SSH key from the host into this volume
@@ -13,14 +11,14 @@ If you need another key, read the documentation of [`pygmy`](linux_pygmy.md) abo
     - container:amazeeio-ssh-agent
   ```
 4. When CLI container starts, the volume is mounted and an entrypoint script adds SHH key into agent.
-  @see https://github.com/amazeeio/lagoon/blob/master/images/php/cli/10-ssh-agent.sh
+  @see https://github.com/uselagoon/lagoon-images/blob/main/images/php-cli/entrypoints/10-ssh-agent.sh
 
 Running `ssh-add -L` within CLI container should show that the SSH key is correctly loaded.
 
 ## Troubleshooting
 ### SSH Key issues
 
-As everything on amazee.io works with key authentication sometimes you might run into issues where the drush aliases aren't displayed or you can't connect to the servers.
+As everything on Lagoon works with key authentication sometimes you might run into issues where the drush aliases aren't displayed or you can't connect to the servers.
 
     Could not load API JWT Token, error was: 'lagoon@ssh.lagoon.amazeeio.cloud: Permission denied (publickey).'
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index ae086c16..70c21c9f 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -28,9 +28,8 @@ If this still is not enough, this is the 🔨  method:
     docker-compose down -v
     docker-compose up
 
-{% hint style='danger' %}
-This will remove your whole local MySQL database and maybe existing other local created volumes (like the solr search index).
-{% endhint %}
+!!! danger
+    This will remove your whole local MySQL database and maybe existing other local created volumes (like the solr search index).
 
 ### Drupal Container logs
 
@@ -54,7 +53,6 @@ To find such issues, we need to analyze the docker logs, do that via:
     amazee_io.docker.amazee.io | Child (246) said Child starts
 
 Check the latest few lines of code and you probably see the issue.
-Stuck here? Join our Slack at [slack.amazee.io](https://slack.amazee.io) and we help you.
 
 ### Shared container logs
 
@@ -121,9 +119,8 @@ You shouldn't really need to do this, and if you think so, first try the above h
 
 This will stop and remove **all** containers and **all** attached volumes.
 
-{% hint style='danger' %}
-This will remove your whole local MySQL database and maybe existing other local created volumes (like the solr search index).
-{% endhint %}
+!!! danger
+    This will remove your whole local MySQL database and maybe existing other local created volumes (like the solr search index).
 
 
 If you get an error like `cannot create temp file for here-document: No space left on device` then you can free up space by removing old volumes and images that we don't need anymore:
diff --git a/mkdocs.yml b/mkdocs.yml
index 73d8c39c..62716a39 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,5 +1,32 @@
-site_name: Pygmy Documentation
-theme: readthedocs
+site_name: 'Pygmy'
+site_url: https://pygmystack.github.io/pygmy/
+repo_url: https://github.com/pygmystack/pygmy/
+repo_name: pygmystack/pygmy
+edit_uri: edit/main/docs
+site_author: The pygmystack authors
+
+theme:
+  name: 'material'
+  palette:
+    primary: 'blue'
+    accent: 'light blue'
+  favicon: images/pygmystack_icon.png
+  logo: images/pygmystack_icon_wh.png
+  icon:
+    repo: fontawesome/brands/github 
+
+markdown_extensions:
+  - toc:
+      permalink: "#"
+      baselevel: 2
+  - admonition
+  - attr_list
+  - tables
+  - pymdownx.highlight
+  - pymdownx.superfences
+
+plugins:
+  - search
 
 nav:
   - Pygmy: index.md
@@ -14,9 +41,3 @@ nav:
   - Mapping additional ports: map_addtitional_ports.md
   - Customisation:
       - Introduction: customisation/introduction.md
-
-markdown_extensions:
-  - toc:
-      permalink: true
-      baselevel: 1
-  - admonition