From b2b18812025b6628988c0feb6c59a2b6413021be Mon Sep 17 00:00:00 2001
From: Scott Leggett <scott@sl.id.au>
Date: Fri, 11 Oct 2024 09:30:59 +0800
Subject: [PATCH] chore: update group docs to describe subgroups and inherited
 roles

---
 .../concepts-basics/building-blocks/groups.md | 37 ++++++++++++++++++-
 mkdocs.yml                                    |  6 ++-
 2 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/docs/concepts-basics/building-blocks/groups.md b/docs/concepts-basics/building-blocks/groups.md
index 69aa5fddb8..172a4d437e 100644
--- a/docs/concepts-basics/building-blocks/groups.md
+++ b/docs/concepts-basics/building-blocks/groups.md
@@ -1,5 +1,38 @@
 # Groups
 
-_Groups_ are made up of users who have roles. An organization can have one or more groups. Each project can be assigned one or more groups. Groups can be assigned to multiple projects. Groups are created independently of projects, and then assigned to them.
+_Groups_ are made up of users who have roles.
+An organization can have one or more groups.
+Each project can be assigned one or more groups.
+Groups can be assigned to multiple projects.
+Groups are created independently of projects, and then assigned to them.
 
-Organizations have a quota to limit the number of groups assigned to it. If you need to change the quota, please contact {{ defaults.helpstring }}.
+Organizations have a quota to limit the number of groups assigned to it.
+If you need to change the quota, please contact {{ defaults.helpstring }}.
+
+# Subgroups
+
+!!! warning
+    Subgroups and not commonly used in Lagoon, and you probably don't need them.
+    However, they can be useful in some situations.
+
+Groups can be nested to an arbitrary depth.
+Subgroups are groups which are a child of another group.
+
+A user's role in an ancestor group is inherited by descendant groups.
+
+## Subgroups example
+
+Consider this group structure:
+
+``` mermaid
+---
+title: Subgroup permissions example
+---
+erDiagram
+    CompanyGroup ||--o{ DivisionGroup : child
+    DivisionGroup ||--o{ TeamGroup : child
+```
+
+If a User has `maintainer` role in the top level `CompanyGroup`, then they will also have `maintainer` level access to projects which are in the `TeamGroup`.
+
+Note that this relationship is indirect: the Project is not in the same group as the User, but because the Project is in a _subgroup_ of the User's group, the User has `maintainer` permissions on the Project.
diff --git a/mkdocs.yml b/mkdocs.yml
index 935e5c75fa..5ffa80535e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -236,7 +236,11 @@ markdown_extensions:
   - pymdownx.tilde
   - pymdownx.tasklist:
       custom_checkbox: true
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+      - name: mermaid
+        class: mermaid
+        format: !!python/name:pymdownx.superfences.fence_code_format
   - tables
   - toc:
       permalink: "#"