From 892b950db94dd23afd1623cb1bfe688d212fafdf Mon Sep 17 00:00:00 2001 From: Adin Ermie Date: Mon, 9 Dec 2024 16:12:04 -0500 Subject: [PATCH] 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 --- README.md | 5 +++ docs/azure/best-practices/azure-ai.md | 3 +- docs/azure/best-practices/be-mindful.md | 6 ++- docs/azure/best-practices/governance.md | 7 ++-- .../deploy-to-the-azure-landing-zone.md | 9 ++-- docs/azure/design-build-deploy/networking.md | 5 ++- docs/azure/support/enterprise-support.md | 7 ++-- new-markdown-document-template.md | 42 +++++++++++++++++++ 8 files changed, 69 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index db68360..012fe08 100644 --- 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 index f54f746..ac0cf04 100644 --- 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 index 6db7dcc..5d967f9 100644 --- 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 index 7b1c14e..ae3665d 100644 --- 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 index 2178ed3..d75440d 100644 --- 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,7 +32,8 @@ az account set --subscription "" az 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) @@ -40,7 +41,8 @@ GitHub Actions is a feature of GitHub that allows you to automate your workflow. ![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) @@ -48,4 +50,5 @@ There are multiple ways to deploy your application to the Azure Landing Zone usi 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 index b2dc74b..a4f99da 100644 --- 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 index 5ffe4df..1e3ef8f 100644 --- 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 index 939a23f..dfc8b49 100644 --- 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 + +--- + ## Related pages