From bf992bd337927387f1b40a1b195198ac1bbd11eb Mon Sep 17 00:00:00 2001
From: Matt White <16320656+matt-FFFFFF@users.noreply.github.com>
Date: Fri, 4 Oct 2024 14:51:27 +0200
Subject: [PATCH] fix: mermaid chart in readme generation with alzlibtool (#64)

* fix: mermaid chart in readme generation with alzlibtool

* chore: update alzlibtool to 0.21.5

* docs(platform/alz): generate docs for alz platform
---
 .github/workflows/pr-check.yml          |  2 +-
 docs/content/assets/role-definitions.md |  4 ++++
 platform/alz/README.md                  | 30 ++++++++++++++++---------
 3 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml
index 8858548..e02f8eb 100644
--- a/.github/workflows/pr-check.yml
+++ b/.github/workflows/pr-check.yml
@@ -57,7 +57,7 @@ jobs:
           go-version: 'stable'
 
       - name: Install alzlibtool
-        run: go install github.com/Azure/alzlib/cmd/alzlibtool@v0.21.3
+        run: go install github.com/Azure/alzlib/cmd/alzlibtool@v0.21.5
 
       - name: Azure login
         uses: azure/login@6c251865b4e6290e7b78be643ea2d005bc51f69a # v2.1.1
diff --git a/docs/content/assets/role-definitions.md b/docs/content/assets/role-definitions.md
index 760f551..ac71b51 100644
--- a/docs/content/assets/role-definitions.md
+++ b/docs/content/assets/role-definitions.md
@@ -21,6 +21,10 @@ Within the resource definition, there are several values that specific to the sc
 These are:
 
 - The resource id (this must end with a UUID)
+- The name (UUID) of the role definition - this must be unique within the tenant
+- The role name (`.properties.roleName`) - this must be unique within the tenant
 - The assignable scopes
 
+We recommend that clients append the management group id to the end of the rolenames to ensure uniqueness.
+
 [Clients](/Azure-Landing-Zones-Library/clients) should be aware of these values and ensure that they are correctly set when deploying the resource.
diff --git a/platform/alz/README.md b/platform/alz/README.md
index b468270..6d435bd 100644
--- a/platform/alz/README.md
+++ b/platform/alz/README.md
@@ -26,25 +26,35 @@ The following architectures are available in this library, please note that the
   
 ```mermaid
 flowchart TD
-  alzroot["ALZ root\n(root)"]
+  alzroot["ALZ root
+(root)"]
   alzroot --> decommissioned
-  decommissioned["Decommissioned\n(decommissioned)"]
+  decommissioned["Decommissioned
+(decommissioned)"]
   alzroot --> landingzones
-  landingzones["Landing zones\n(landing_zones)"]
+  landingzones["Landing zones
+(landing_zones)"]
   landingzones --> corp
-  corp["Corp\n(corp)"]
+  corp["Corp
+(corp)"]
   landingzones --> online
-  online["Online\n(online)"]
+  online["Online
+(online)"]
   alzroot --> platform
-  platform["Platform\n(platform)"]
+  platform["Platform
+(platform)"]
   platform --> connectivity
-  connectivity["Connectivity\n(connectivity)"]
+  connectivity["Connectivity
+(connectivity)"]
   platform --> identity
-  identity["Identity\n(identity)"]
+  identity["Identity
+(identity)"]
   platform --> management
-  management["Management\n(management)"]
+  management["Management
+(management)"]
   alzroot --> sandboxes
-  sandboxes["Sandboxes\n(sandboxes)"]
+  sandboxes["Sandboxes
+(sandboxes)"]
 
 ```