Added Call-Outs (#66)

* Added call-out examples * Added markdown linting * Added markdown lint control file * Increased line length rule * Removed Markdown linting --------- Co-authored-by: Adin Ermie <[email protected]>
bcgov · Dec 9, 2024 · 892b950 · 892b950
1 parent 1582e7c
commit 892b950
Show file tree

Hide file tree

Showing 8 changed files with 69 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -12,6 +12,11 @@ Please see [Writing guide for Platform Services technical documentation](https:/
 
 Start your new document from the new [Markdown document template](/new-markdown-document-template.md).
 
+## Call-Outs
+To add call-outs to your markdown content, please refer to the following links for supported types and syntax:
+https://developer.gov.bc.ca/docs/default/component/bc-developer-guide/content-syntax-guide/#admonitions
+https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types
+
 # Deploy locally
 To deploy locally you need to have Node.js installed. If you don't have it installed, you can download it from [here](https://nodejs.org/en/download/). You will also need to have Docker installed. If you don't have it installed, you can download it from [here](https://www.docker.com/products/docker-desktop).
 

diff --git a/docs/azure/best-practices/azure-ai.md b/docs/azure/best-practices/azure-ai.md
@@ -20,7 +20,8 @@ When using Azure AI services, you may need to deploy a Virtual Machine within th
 
 The simplest method to do this, is to deploy an [Azure Bastion](https://learn.microsoft.com/en-us/azure/bastion/quickstart-host-portal) within your virtual network.
 
-> Note: The minimum Bastion SKU required is **Basic**, as the **Developer** tier is not currently available in the Canada regions.
+!!! question "Azure Bastion SKU"
+    The minimum Bastion SKU required is **Basic**, as the **Developer** tier is not currently available in the Canada regions.
 
 This does require a specific Subnet to be created within the VNet. The subnet name must be **AzureBastionSubnet**. The subnet address range that you specify must be **/26 or larger** (for example, /25 or /24). After adding this subnet to your virtual network, you can deploy Bastion.
 

diff --git a/docs/azure/best-practices/be-mindful.md b/docs/azure/best-practices/be-mindful.md
@@ -30,7 +30,8 @@ In some scenarios, you may have a need to create a custom DNS Zone. Generally, t
 
 If this is your scenario, please submit a [Public Cloud Support request](https://citz-do.atlassian.net/servicedesk/customer/portal/3), so that the Public Cloud team can work with you to create and attach the custom DNS Zone to the central Private DNS Resolver.
 
-> Note: Attaching your custom Private DNS Zone to your Virtual Network (VNet) will not work, as all DNS queries are routed through the central Private DNS Resolver.
+!!! failure "Custom DNS Zones"
+    Attaching your custom Private DNS Zone to your Virtual Network (VNet) will not work, as all DNS queries are routed through the central Private DNS Resolver.
 
 ## Using Terraform to create Subnets
 
@@ -40,7 +41,8 @@ The Azure Landing Zones have an Azure Policy implemented that requires every sub
 
 Therefore, instead of using the `azurerm_subnet` resource to create subnets, you must use the `azapi_update_resource` resource from the [AzAPI Terraform Provider](https://registry.terraform.io/providers/Azure/azapi/latest/docs). This resource allows you to create subnets with an associated NSG in a single step.
 
-> Note: You need to use the `azapi_update_resource` resource, because you are updating an existing Virtual Network (VNet) with a new subnet (and associated Network Security Group).
+!!! abstract "AzAPI Resource Provider"
+    You need to use the `azapi_update_resource` resource, because you are updating an existing Virtual Network (VNet) with a new subnet (and associated Network Security Group).
 
 **Example code:**
 

diff --git a/docs/azure/best-practices/governance.md b/docs/azure/best-practices/governance.md
@@ -22,9 +22,8 @@ Within the Azure portal, navigate to [Azure Policy](https://portal.azure.com/#vi
 
 Within the Azure portal, navigate to the [Cost Management - Cost Analysis](https://portal.azure.com/#blade/Microsoft_Azure_CostManagement/Menu/costanalysis) view. This service provides a centralized view of the costs of your Azure environments.
 
-> **IMPORTANT**
->
-> Please make sure that you select the appropriate **Scope** to view the costs of your environment.
-> ![Azure Cost Management - Scope](../images/azure-cost-management-scope.png "Azure Cost Management - Scope")
+!!! example "View Scope"
+    Please make sure that you select the appropriate **Scope** to view the costs of your environment.
+    ![Azure Cost Management - Scope](../images/azure-cost-management-scope.png "Azure Cost Management - Scope")
 
 For more detail about managing costs, see the **Understand your billing** > [Azure Cost Management](../understanding-your-bill/azure-billing-and-cost-management.md) section.
diff --git a/docs/azure/design-build-deploy/deploy-to-the-azure-landing-zone.md b/docs/azure/design-build-deploy/deploy-to-the-azure-landing-zone.md
@@ -32,20 +32,23 @@ az account set --subscription "<your-Azure-subscription-ID>"
 az <AZURE RESOURCE TYPE> create ...
 ```
 
-**Note:** There are other command-line tools like [Azure PowerShell](https://learn.microsoft.com/en-us/powershell/azure/), that you can use to create and manage your Azure resources. You can choose the tool that you are most comfortable with.
+!!! note "Other Command-Line Tools"
+    There are other command-line tools like [Azure PowerShell](https://learn.microsoft.com/en-us/powershell/azure/), that you can use to create and manage your Azure resources. You can choose the tool that you are most comfortable with.
 
 ## GitHub Actions / Infrastructure-as-Code (IaC)
 
 GitHub Actions is a feature of GitHub that allows you to automate your workflow. Microsoft developed **GitHub Actions for Azure** and designed them be used with Azure. You can see all of the GitHub Actions for Azure in the [GitHub Marketplace](https://github.com/marketplace?query=Azure&type=actions){:data-proofer-ignore}.
 
 ![GitHub Actions for Azure](../images/azure-github-actions-marketplace.png "GitHub Actions for Azure")
 
-**Note:** Be sure to review the [CI/CD Best Practices](../best-practices/ci-cd.md) before implementing GitHub Actions.
+!!! tip
+    Be sure to review the [CI/CD Best Practices](../best-practices/ci-cd.md) before implementing GitHub Actions.
 
 ### Infrastructure-as-Code (IaC)
 
 There are multiple ways to deploy your application to the Azure Landing Zone using Infrastructure-as-Code (IaC). You can use tools like [Terraform](https://www.terraform.io/), [Azure Resource Manager (ARM) templates](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/), [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview?tabs=bicep), [Ansible](https://learn.microsoft.com/en-us/azure/developer/ansible/overview), [Chef](https://learn.microsoft.com/en-us/azure/developer/chef/overview), or [Pulumi](https://devblogs.microsoft.com/devops/infrastructure-as-code-azure-python-wpulumi/) to define your Infrastructure-as-Code and deploy it to Azure.
 
 While we don't have a specific example for each tool, we recommend that you choose the tool that you are most comfortable with and that best fits your needs.
 
-**Important:** If you are using Terraform to deploy your application to Azure, please take note of the following: [Using Terraform to Create Subnets](../best-practices/be-mindful.md#using-terraform-to-create-subnets) and [AzAPI Terraform Provider (using azapi_update_resource)](../best-practices/be-mindful.md#azapi-terraform-provider-using-azapi_update_resource).
+!!! warning "Using Terraform for IaC"
+    If you are using Terraform to deploy your application to Azure, please take note of the following: [Using Terraform to Create Subnets](../best-practices/be-mindful.md#using-terraform-to-create-subnets) and [AzAPI Terraform Provider (using azapi_update_resource)](../best-practices/be-mindful.md#azapi-terraform-provider-using-azapi_update_resource).
diff --git a/docs/azure/design-build-deploy/networking.md b/docs/azure/design-build-deploy/networking.md
@@ -8,9 +8,10 @@ This VNet is connected with the central hub (vWAN), and receives default routes
 
 There are no subnets that are pre-created within the VNet. Each team is responsible for creating their own subnets based on their requirements. Subnets should be created within the VNet to segment resources based on their function or security requirements.
 
-**IMPORTANT:** There are some security controls in place, that require every subnet to have an associated [Network Security Group (NSG)](https://learn.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview). This may cause some challenges when creating subnets. The simplest approach is to create a NSG first, and then create the subnet (with the NSG associated with it).
+!!! danger "Security Controls for Subnets"
+    There are some security controls in place, that require every subnet to have an associated [Network Security Group (NSG)](https://learn.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview). This may cause some challenges when creating subnets. The simplest approach is to create a NSG first, and then create the subnet (with the NSG associated with it).
 
-For further guidance on creating subnets with associated NSGs (specifically using Terraform), refer to the [Be Mindful](../best-practices/be-mindful.md#using-terraform-to-create-subnets) documentation.
+    For further guidance on creating subnets with associated NSGs (specifically using Terraform), refer to the [Be Mindful](../best-practices/be-mindful.md#using-terraform-to-create-subnets) documentation.
 
 ## Spoke-to-Spoke connectivity
 

diff --git a/docs/azure/support/enterprise-support.md b/docs/azure/support/enterprise-support.md
@@ -4,9 +4,10 @@ Last updated: **{{ git_revision_date_localized }}**
 
 Once your Project Set has been provisioned, each Azure Subscription will be enrolled in the Azure Unified Support plan. There is a delay of approximately **2 weeks** for the Azure Unified Support plan to be activated.
 
-> **Note:** If you use a third-party vendor's landing zone in Azure, you can't use the B.C. government's Unified Enterprise support plan for applications hosted in the vendor's landing zone.  
-> 
-> Ministry teams working in the OCIO-managed landing zone in Azure can currently access the Unified Enterprise support services for free.  
+!!! info
+    If you use a third-party vendor's landing zone in Azure, you can't use the B.C. government's Unified Enterprise support plan for applications hosted in the vendor's landing zone.  
+
+    Ministry teams working in the OCIO-managed landing zone in Azure can currently access the Unified Enterprise support services for free. 
 
 You can view the full list of services available to the ministries under the [Unified Enterprise support plan](https://www.microsoft.com/en-IN/microsoft-unified/plan-details){:data-proofer-ignore}.
 

diff --git a/new-markdown-document-template.md b/new-markdown-document-template.md
@@ -28,6 +28,48 @@ This is paragraph text that appears under the second heading.
 
 ---
 
+## Call-Outs
+
+To add call-outs to your markdown content, please refer to the following links for supported types and syntax:
+
+!!! note "Note"
+    This is a note
+
+!!! abstract "Abstract"
+    This is an abstract
+
+!!! info "Information"
+    This is information
+
+!!! tip "Tip"
+    This is a tip
+
+!!! success "Success"
+    This is a success
+
+!!! question "Question"
+    This is a question
+
+!!! warning "Warning"
+    This is a warning
+
+!!! failure "Failure"
+    This is a failure
+
+!!! danger "Danger"
+    This is danger
+
+!!! bug "Bug"
+    This is a bug
+
+!!! example "Example"
+    This is an example
+
+!!! quote "Quote"
+    This is a quote
+
+---
+
 <!-- Notice again --- separator to present related pages next  -->
 ## Related pages