docs: add extensibility docs

docs/content/_index.md

@@ -9,15 +9,15 @@ Welcome to the Azure Landing Zones Library. This library is a collection of reso
 
 For an example, please see the alz library member in the `platform/alz` directory of the [repository](https://github.com/Azure/Azure-Landing-Zones-Library/tree/main/platform/alz).
 
-For more information on why we built this, see the [Why](/Azure-Landing-Zones-Library/why) section.
+For more information on why we built this, see the [Why]({{< relref "why" >}}) section.
 
 ## What types of things can you find in the library?
 
-See the [Library Assets](/Azure-Landing-Zones-Library/assets) section for more information.
+See the [Library Assets]({{< relref "assets" >}}) section for more information.
 
 ## How can you consume the library?
 
-See the [Library Clients](/Azure-Landing-Zones-Library/clients) section for more information.
+See the [Library Clients]({{< relref "clients" >}}) section for more information.
 
 ## Library structure
 

docs/content/extensibility/index.md

@@ -0,0 +1,85 @@
+---
+title: Extensibility
+geekdocNav: true
+# geekdocAlign: center
+geekdocAnchor: true
+---
+
+The Azure Landing Zones Library is designed to be flexible:
+
+- ✅ You want to fork host your own version of the library? You can do that!
+- ✅ You want to be able to extend the library with your own constructs, and use them in your own deployments? You can do that as well!
+- ✅ You want to be able to consume the library with your own client? You can do that too!
+- ✅ You want to host your own personal customizations based on published library assets? You guessed it, you can do that!
+
+## On dependencies
+
+If you host your own library, we recommend that you use create a [`alz_library_metadata.json`]({{< relref "assets/metadata" >}}) file in the root of your library directory to provide metadata about your library.
+In this file you should include any dependencies.
+
+Alternatively you can supply the dependent library to your client.
+In the ALZ Terraform provider, you can include the dependent library in the `library_references` field of the provider configuration.
+
+By default, your client will not allow you to add assets to the library that already exist.
+For example, you cannot create an another architecture called `alz` when you are using the `platform/alz` library.
+We recommend that you use unique naming for your assets to avoid conflicts.
+
+If you are unable to avoid conflicts, you can use configure your client to allow you to override assets in the library.
+In the ALZ Terraform provider, you can set the [`library_overwrite_enabled`](https://registry.terraform.io/providers/Azure/alz/latest/docs#library_overwrite_enabled-1) field of the provider configuration.
+
+## Forking or hosting your own version of the library
+
+You may wish to fork the library and host your own version of it, or you may wish to host your own extensions to this library.
+Examples are:
+
+- Customizing the architecture definitions to suit your own needs, e.g. naming conventions
+- Including your own policy assets
+- Removing or modifying policy assets in this library that you do not wish to use (using [archetype overrides]({{< relref "assets/archetype-overrides" >}}))
+
+Library clients should be able to access the library from a variety of sources, including git, local file system, or a URL.
+The [`alzlib`](https://github.com/Azure/alzlib) library client uses the [`hashicorp/go-getter`](https://github.com/hashicorp/go-getter) library to fetch the library from a variety of sources.
+
+{{< hint type=important icon=gdoc_check_circle_outline title="Dependencies" >}}
+Dependencies are transitive, so if you include a dependency in your library, you do not need to explicitly include any dependants of your dependencies.
+{{< /hint >}}
+
+You can either add dependencies to the Azure Landing Zones Library, or a custom URL.
+Custom URLs can be any URL supported by `go-getter`, including git repositories, local file systems, or HTTP URLs.
+
+### Using a local filesystem
+
+This example shows how to configure the ALZ Terraform provider with a local library.
+This is common for when you want to augment the ALZ library with your own customizations.
+
+This will replace the default `library_referneces` value, which is pinned to a version of the ALZ Library, see the [provider docs](https://registry.terraform.io/providers/Azure/alz/latest/docs#library_references-1) for more information:
+
+```terraform
+provider "alz" {
+  library_references = [
+    {
+      custom_url = "${path.root}/lib"
+    },
+    # If you do not host metadata in your local library then include any dependencies here...
+  ]
+}
+```
+
+## Changing the default library Git URL
+
+Using environment variables, you can change the git URL that the `alzlib` client uses, the default is: `github.com/Azure/Azure-Landing-Zones-Library`.
+This is useful if you want to use a different library URL for your deployments, or if you are testing updates in a fork before making a pull request back to the upstream repo.
+This is documented [here](https://github.com/Azure/alzlib?tab=readme-ov-file#configuration).
+
+Using the `ALZLIB_LIBRARY_GIT_URL` environment variable is only supported with the git protocol.
+The value is appended to the `git::` prefix to force the `go-getter` library to use the git protocol.
+
+{{< hint type=important icon=gdoc_check_circle_outline title="Git authentication" >}}
+Do not include your Git credentials in your library reference or dependency URLs.
+Instead, configure Git to use valid credentials for the URL you are using before running the `alzlib` client.
+{{< /hint >}}
+
+### Example
+
+```bash
+export ALZLIB_LIBRARY_GIT_URL="https://FabrikamFiber01@dev.azure.com/FabrikamFiber01/FabrikamFiber01-01/_git/FabrikamFiber01-01"
+```

docs/content/why.md

@@ -7,14 +7,17 @@ geekdocAnchor: true
 
 First some history...
 
-With the original ALZ Terraform ([caf-enterprise-scale](https://registry.terraform.io/modules/Azure/caf-enterprise-scale/azurerm/latest)) module we always had the concept of a library, but it was built into the module.
+The concept of the library began with the original ALZ Terraform ([caf-enterprise-scale](https://registry.terraform.io/modules/Azure/caf-enterprise-scale/azurerm/latest)), but it was (and still is) built into that module.
 In the [early days of alzlib](https://github.com/Azure/alzlib/tree/v0.9.0), we also embedded the library into the Go module.
 
-This tight coupling made it difficult to update the library without updating the module - it was impossible to seperate module feature updates from library updates.
+This tight coupling made it difficult to update the library without updating the module - it was impossible to separate module feature updates from library updates.
 If you wanted the most up to date policies, then you also had to take the latest module feature updates too.
 
-We therefore decoupled the library from the module and created this repository.
-Because the library is now a seperate entity, it can be updated and version controlled independently of the module.
+This design also made the library useful only for Terraform users, and not for other clients.
+We had the idea to decouple the library from the Terraform module, and this repository is the result.
+We plan that this library will be the source of truth for all Azure Landing Zones assets.
+
+Because the library is now a separate entity, it can be updated and version controlled independently of the module.
 It also has the added benefit of being able to be consumed by other clients, not just Terraform.
 
 ## Benefits

docs/themes/hugo-geekdoc/layouts/_default/_markup/render-codeblock-mermaid.html

@@ -1,8 +1,8 @@
 <!-- prettier-ignore-start -->
 {{ if not (.Page.Scratch.Get "mermaid") }}
-  <!-- Include mermaid only first time -->
-  <script defer src="{{ index (index .Page.Site.Data.assets "mermaid.js") "src" | relURL }}"></script>
-  {{ .Page.Scratch.Set "mermaid" true }}
+<!-- Include mermaid only first time -->
+<script defer src="{{ index (index .Page.Site.Data.assets " mermaid.js") "src" | relURL }}"></script>
+{{ .Page.Scratch.Set "mermaid" true }}
 {{ end }}
 <!-- prettier-ignore-end -->
 

docs/themes/hugo-geekdoc/layouts/_default/_markup/render-link.html

@@ -1,14 +1,11 @@
-{{- $raw := or (hasPrefix .Text "<img") (hasPrefix .Text "<figure") -}}
-{{- $code := hasPrefix .Text "<code" -}}
-<a
+{{- $raw := or (hasPrefix .Text "<img") (hasPrefix .Text "<figure" ) -}} {{- $code :=hasPrefix .Text "<code" -}} <a
   class="gdoc-markdown__link{{ if $raw -}}
     --raw
   {{- else if $code -}}
     --code
-  {{- end }}"
-  href="{{ .Destination | safeURL }}"
-  {{- with .Title }}{{ printf "title=\"%s\"" . | safeHTMLAttr }}{{- end }}
->
+  {{- end }}" href="{{ .Destination | safeURL }}" {{- with .Title }}{{ printf "title=\" %s\"" . | safeHTMLAttr}}{{ end
+  }}{{ if or (strings.HasPrefix .Destination "http" ) (strings.HasPrefix .Destination "https" ) }} target="_blank" {{-
+  end }}>
   {{- .Text | safeHTML -}}
-</a>
-{{- /* Drop trailing newlines */ -}}
+  </a>
+  {{- /* Drop trailing newlines */ -}}