en-US/about_PSDocs_Azure_Badges.help.txt
|
TOPIC
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:  For example, a Github Actions badge for PSDocs.Azure would be:  To include badges images with a clickable link use standard markdown syntax: [](https://link_uri) For example, an Azure Pipelines badge for PSDocs.Azure would be: [](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:  [](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:  [](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 |