Publish to Azure Storage

After generating markdown from Azure templates using you may want to publish these files for consumption. A simple approach is to publish the files directly to Azure Blob Storage.

Abstract

This topic covers using a pipeline to publish markdown generated by PSDocs for Azure to blob storage.

GitHub Actions

Extend your GitHub Actions workflow .github/workflows/publish-docs.yaml created previously by completing the following steps:

• Add a new step to upload files to storage.

- name: 'Copy files to Azure Storage'
  uses: bacongobbler/azure-blob-storage-upload@v1.1.1
  with:
    connection_string: ${{ secrets.STORAGE_ACCOUNT_SECRET }}
    container_name: docs
    source_dir: 'out/docs/*'

• Create an encrypted secret STORAGE_ACCOUNT_SECRET for the action to use. The secret value is a connection string with permissions to uploads files to the storage account.

The bacongobbler/azure-blob-storage-upload action is used to upload the markdown files to the docs blob storage container.

Example

name: Publish docs
on:
  push:
    branches: [ main ]
jobs:
  publish:
    name: Publish
    runs-on: ubuntu-latest
    steps:

    - uses: actions/checkout@v2

    # Generate markdown files using PSDocs
    # Scan for Azure template file recursively in the templates/ directory
    # Then generate a docs using a standard naming convention. i.e. <name>_<version>.md
    - name: Generate docs
      run: |
        Install-Module -Name 'PSDocs.Azure' -Repository PSGallery -Force;
        Get-AzDocTemplateFile -Path templates/ | ForEach-Object {
          Invoke-PSDocument -Module PSDocs.Azure -OutputPath out/docs/ -InputObject $_.TemplateFile -Convention 'Azure.NameByParentPath';
        }
      shell: pwsh

    - name: 'Copy files to Azure Storage'
      uses: bacongobbler/azure-blob-storage-upload@v1.1.1
      with:
        connection_string: ${{ secrets.STORAGE_ACCOUNT_SECRET }}
        container_name: docs
        source_dir: 'out/docs/*'

Azure Pipelines

Extend your Azure DevOps YAML pipeline .azure-pipelines/publish-docs.yaml created previously by completing the following steps:

• Add a new step to upload files to storage.

- task: AzureFileCopy@4
  displayName: 'Copy files to Azure Storage'
  inputs:
    SourcePath: 'out/docs/*'
    azureSubscription: '<enter>'
    Destination: 'AzureBlob'
    storage: '<enter>'
    ContainerName: 'docs'

• Set azureSubscription and storage inputs with the name of your Azure service connection and storage account.

The AzureFileCopy task is used to upload the markdown files to the docs blob storage container.

Example

jobs:
- job: 'Publish'
  displayName: 'Generate ARM template docs'
  pool:
    vmImage: 'windows-2019'
  steps:

  # Generate markdown files using PSDocs
  # Scan for Azure template file recursively in the templates/ directory
  # Then generate a docs using a standard naming convention. i.e. <name>_<version>.md
  - powershell: |
      Install-Module -Name 'PSDocs.Azure' -Repository PSGallery -Force;
      Get-AzDocTemplateFile -Path templates/ | ForEach-Object {
        Invoke-PSDocument -Module PSDocs.Azure -OutputPath out/docs/ -InputObject $_.TemplateFile -Convention 'Azure.NameByParentPath';
      }
    displayName: 'Generate docs'

  - task: AzureFileCopy@4
    displayName: 'Copy files to Azure Storage'
    inputs:
      SourcePath: 'out/docs/*'
      azureSubscription: '<enter>'
      Destination: 'AzureBlob'
      storage: '<enter>'
      ContainerName: 'docs'

---

Last update: 2022-05-19