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.
```yaml
- 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][1] `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][2] action is used to upload the markdown files to the `docs` blob storage container.
??? Example
```yaml
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.
```yaml
- 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][3] task is used to upload the markdown files to the `docs` blob storage container.
??? Example
```yaml
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'
```