Improvements to AVM documentation links (Azure#3078)

Author: BernieWhite

docs/analyzing-resources.md

@@ -123,4 +123,4 @@ suppression:
 PSRule for Azure comes with many configuration options.
 The setup section explains in detail how to configure each option.
 
-  [5]: setup/configuring-options.md
+  [5]: setup/index.md

docs/creating-your-pipeline.md

@@ -335,7 +335,7 @@ configuration:
 PSRule for Azure comes with many configuration options.
 The setup section explains in detail how to configure each option.
 
-  [5]: setup/configuring-options.md
+  [5]: setup/index.md
 
 ## Recommended content
 

docs/en/rules/Azure.AI.DisableLocalAuth.md

@@ -92,6 +92,8 @@ resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
 }
 ```
 
+<!-- external:avm avm/res/cognitive-services/account disableLocalAuth -->
+
 ### Configure with Azure Policy
 
 To address this issue at runtime use the following policies:

docs/en/rules/Azure.AI.ManagedIdentity.md

@@ -93,6 +93,8 @@ resource language 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
 }
 ```
 
+<!-- external:avm avm/res/cognitive-services/account managedIdentities -->
+
 ### Configure with Azure Policy
 
 To address this issue at runtime use the following policies:

docs/en/rules/Azure.AI.PrivateEndpoints.md

@@ -90,6 +90,8 @@ resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
 }
 ```
 
+<!-- external:avm avm/res/cognitive-services/account publicNetworkAccess -->
+
 ## LINKS
 
 - [SE:06 Network controls](https://learn.microsoft.com/azure/well-architected/security/networking)

docs/en/rules/Azure.AI.PublicAccess.md

@@ -90,6 +90,8 @@ resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
 }
 ```
 
+<!-- external:avm avm/res/cognitive-services/account networkAcls,publicNetworkAccess -->
+
 ## LINKS
 
 - [SE:06 Network controls](https://learn.microsoft.com/azure/well-architected/security/networking)

docs/en/rules/Azure.AKS.SecretStore.md

@@ -178,6 +178,8 @@ resource cluster 'Microsoft.ContainerService/managedClusters@2021-07-01' = {
 }
 ```
 
+<!-- external:avm avm/res/container-service/managed-cluster enableKeyvaultSecretsProvider -->
+
 ### Configure with Azure CLI
 
 ```bash

docs/en/rules/Azure.AKS.SecretStoreRotation.md

@@ -180,6 +180,8 @@ resource cluster 'Microsoft.ContainerService/managedClusters@2021-07-01' = {
 }
 ```
 
+<!-- external:avm avm/res/container-service/managed-cluster enableSecretRotation -->
+
 ### Configure with Azure CLI
 
 ```bash

docs/en/rules/Azure.AKS.UptimeSLA.md

@@ -129,6 +129,8 @@ resource aks 'Microsoft.ContainerService/managedClusters@2023-02-01' = {
 }
 ```
 
+<!-- external:avm avm/res/container-service/managed-cluster skuTier -->
+
 ## NOTES
 
 `Basic` and `Paid` are removed in the `2023-02-01` and `2023-02-02 Preview` API version,

docs/en/rules/Azure.APIM.MultiRegion.md

@@ -15,7 +15,9 @@ Enhance service availability and resilience by deploying API Management instance
 
 ## DESCRIPTION
 
-API Management supports multi-region deployment, which allows the API gateway to be available in more than one region. This configuration enhances service availability by ensuring that if one region experiences an outage, the API gateway remains operational in another region. Multi-region deployment is crucial for maintaining high availability and reducing latency for global users.
+API Management supports multi-region deployment, which allows the API gateway to be available in more than one region.
+This configuration enhances service availability by ensuring that if one region experiences an outage, the API gateway remains operational in another region.
+Multi-region deployment is crucial for maintaining high availability and reducing latency for global users.
 
 This feature is available exclusively in the Premium SKU for API Management.
 
@@ -93,9 +95,10 @@ resource apiManagementService 'Microsoft.ApiManagement/service@2021-12-01-previe
 
 It is recommended to configure zone redundancy if the region supports it.
 
-Virtual network settings must be configured in the added region, if networking is configured in the existing region or regions. The rule does not take this into consideration.
+Virtual network settings must be configured in the added region, if networking is configured in the existing region or regions.
+The rule does not take this into consideration.
 
-For developer environments, suppressing the rule might make sense as configuring multi-region for an API Management instance requries the `Premium` SKU currently.
+For developer environments, suppressing the rule might make sense as configuring multi-region for an API Management instance requires the `Premium` SKU currently.
 
 ## LINKS
 

docs/en/rules/Azure.APIM.MultiRegionGateway.md

@@ -96,6 +96,8 @@ resource apiManagementService 'Microsoft.ApiManagement/service@2021-12-01-previe
 }
 ```
 
+<!-- external:avm avm/res/api-management/service additionalLocations -->
+
 ## LINKS
 
 - [Resiliency and dependencies](https://learn.microsoft.com/azure/architecture/framework/resiliency/design-resiliency)

docs/en/rules/Azure.APIM.Protocols.md

@@ -137,6 +137,8 @@ resource service 'Microsoft.ApiManagement/service@2021-08-01' = {
 }
 ```
 
+<!-- external:avm avm/res/api-management/service customProperties -->
+
 ## LINKS
 
 - [Data encryption in Azure](https://learn.microsoft.com/azure/architecture/framework/security/design-storage-encryption#data-in-transit)

docs/hooks/shortcodes.py

@@ -167,7 +167,7 @@ def _external_reference_avm(text: str, page: Page) -> str:
     avm_latest_version = _avm_module_latest_tag(page, avm_path)
 
     # Add the reference syntax.
-    syntax_body = _avm_code_reference(avm_path, None)
+    syntax_body = f"\nTo reference the module, please use the following syntax:{_avm_code_reference(avm_path, None)}"
 
     # Add suggested version.
     suggestion_body = ''
@@ -179,10 +179,13 @@ def _external_reference_avm(text: str, page: Page) -> str:
     if avm_latest_version != '':
         latest_body = f"\n\nTo use the latest version:{_avm_code_reference(avm_path, avm_latest_version)}"
 
+    # Add AVM info.
+    avm_links_body = f"\n\n---\n\n- [What is Azure Verified Modules?](https://aka.ms/avm)\n- [Usage and parameters for this module](https://github.com/Azure/bicep-registry-modules/tree/main/{avm_path})"
+
     return _reference_block(
         style = "Example",
         title = f"Configure with [Azure Verified Modules](https://github.com/Azure/bicep-registry-modules/tree/main/{avm_path})",
-        text = f"A pre-built module provided by Microsoft is available from the Azure Bicep public registry.\nTo reference the module, please use the following syntax:{syntax_body}{suggestion_body}{latest_body}"
+        text = f"A pre-validated module supported by Microsoft is available from the Azure Bicep public registry.{syntax_body}{suggestion_body}{latest_body}{avm_links_body}"
     )
 
 def _avm_code_reference(path: str, version: str) -> str:

docs/setup/configuring-expansion.md

@@ -11,7 +11,7 @@ This feature can be enabled by using the following configuration options.
     Each of these configuration options are set within the `ps-rule.yaml` file.
     To learn how to set configuration options see [Configuring options][1].
 
-  [1]: configuring-options.md
+  [1]: index.md
 
 ## Available options