Skip to content

Latest commit

 

History

History
91 lines (59 loc) · 3.8 KB

about_PSDocs_Azure_Badges.md

File metadata and controls

91 lines (59 loc) · 3.8 KB
Raw

PSDocs_Azure_Badges

about_PSDocs_Azure_Badges

SHORT DESCRIPTION

Describes how to insert template badges in to documentation.

LONG DESCRIPTION

PSDocs allows external files to be included in Azure template documentation. Commonly this concept is used to include images that represent the validation status of the template. These images, are commonly referred to as badges. PSDocs can include badges that have been generated by an external validation tool.

To include badge markdown:

  • Create a sub-directory called .ps-docs in the working path of PSDocs. This would normally be root directory ($PWD) of the repository where your Azure template are stored.
  • Create a file named azure-template-badges.md within the .ps-docs sub-directory.
  • When creating all files and folder use lower case names.

The contents of this file is automatically inserted in generated output after the title but before description.

Include badges

To include badge images use standard markdown syntax within the azure-template-badges.md file.

Markdown uses links to reference images. A person viewing the page must have permissions to view the source image. If not, the badge may be shown as a broken or placeholder image.

For example:

![label](https://image_uri)

For example, a Github Actions badge for PSDocs.Azure would be:

![Analyze](https://github.com/Azure/PSDocs.Azure/workflows/Analyze/badge.svg)

To include badges images with a clickable link use standard markdown syntax:

[![label](https://image_uri)](https://link_uri)

For example, an Azure Pipelines badge for PSDocs.Azure would be:

[![Build Status](https://dev.azure.com/PSDocs/PSDocs.Azure/_apis/build/status/PSDocs.Azure-CI?branchName=refs%2Fpull%2F44%2Fmerge)](https://dev.azure.com/PSDocs/PSDocs.Azure/_build/latest?definitionId=1&branchName=refs%2Fpull%2F44%2Fmerge)

Dynamic links

In additional to inserting static content, some replacement tokens have been defined. When specified within azure-template-badges.md each token will be replaced when the file is included. The following replacement tokens have been defined:

  • {{ template_path }} - The relative path of the template directory.
  • {{ template_path_encoded }} - The relative path of the template directory URL encoded.

For example, if the template path was .\templates\storage\v1\template.json the following would be used:

  • {{ template_path }} = templates/storage/v1
  • {{ template_path_encoded }} = templates%2fstorage%2fv1

The follow example shows source markdown for including badges:

![Best Practice Check](https://azurequickstartsservice.blob.core.windows.net/badges/{{ template_path }}/BestPracticeResult.svg)
[![Deploy To Azure](https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/1-CONTRIBUTION-GUIDE/images/deploytoazure.svg?sanitize=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-quickstart-templates%2Fmaster%2F{{ template_path_encoded }}%2Fazuredeploy.json)

After replacement the following would be the resulting output included in the template document:

![Best Practice Check](https://azurequickstartsservice.blob.core.windows.net/badges/templates/storage/v1/BestPracticeResult.svg)
[![Deploy To Azure](https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/1-CONTRIBUTION-GUIDE/images/deploytoazure.svg?sanitize=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-quickstart-templates%2Fmaster%2Ftemplates%2fstorage%2fv1%2Fazuredeploy.json)

NOTE

An online version of this document is available at https://github.com/Azure/PSDocs.Azure/blob/main/docs/concepts/en-US/about_PSDocs_Azure_Badges.md.

KEYWORDS

  • Badge