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

@@ -57,7 +57,7 @@ jobs:
           go-version: 'stable'
 
       - name: Install alzlibtool
-        run: go install github.com/Azure/alzlib/cmd/[email protected].3
+        run: go install github.com/Azure/alzlib/cmd/[email protected].5
 
       - name: Azure login
         uses: azure/login@6c251865b4e6290e7b78be643ea2d005bc51f69a # v2.1.1

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.

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)"]
 
 ```