PSDocs.Azure

0.3.0

en-AU/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:
 
    ![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