Mermaid diagrams in ADO workaround

ConvertFrom-MarkdownTemplate.ps1

# This script file regenerates all the generated markdown files.
# This is needed because Azure DevOps (ADO) does not support mermaid charts 
# in the preview pane. Once ADO supports this functionality, remove
# this script, delete the generated files, move and rename the template 
# files, and update the links that are going to the generated files.
# Requires a directory structure like so
# |- docs
#   |- scripts
#     |- ConvertFrom-MarkdownTemplate.ps1
#   |- templates
#     |- example.template.md
#   |- generated
#     |- example.md (gets generated)

# Get current directory so we can restore our location later.
$currentDir = Get-Location

# This script stored in /docs/scripts, docs folder is one directory up.
$documentationFolder = "$PSScriptRoot\.."
$templatesFolder = "$documentationFolder\templates"
$generatedFolder = "$documentationFolder\generated"

Set-Location $documentationFolder

# Install needed tools, chocolately, nodejs, and the mermaid charts cli tool.
$overrideReinstall = $false

# Install chocolately if not installed
$chocoVersion = powershell choco -v
if (-not($chocoVersion) -or $overrideReinstall) {
    Write-Output 'Chocolatey is not installed, installing...'
    Set-ExecutionPolicy Bypass -Scope Process -Force; 
    Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
} else {
    Write-Output "Chocolatey Version $chocoVersion is already installed."
}

# Install nodejs if not installed
$npmVersion = powershell npm -v
if (-not($npmVersion) -or $overrideReinstall) {
    Write-Output 'nodejs is not installed, installing...'
    choco install nodejs
} else {
    Write-Output "nodejs $chocoVersion is already installed."
}

# Install mermaid cli if not installed
$npmListArray = npm ls -g --json
$npmJson = $npmListArray -join ' '  
$npmObject = ConvertFrom-Json $npmJson
$mermaidVersion = $npmObject.dependencies.'@mermaid-js/mermaid-cli'.version

if (-not($mermaidVersion) -or $overrideReinstall) {
    & 'C:\Program Files\nodejs\npm.cmd' install -g @mermaid-js/mermaid-cli
} else {
    Write-Output "mermaid-cli $mermaidVersion is already installed."
}

# Check for modified generated files as a sanity check so we don't accidentally wipe out modifications.
git status -s | ForEach-Object {
    $gitStatusParts = $_ -split ' '
    if ($gitStatusParts[2] -match '/generated/') {
        Write-Host "Modified generated files detected.`nDouble check that you have not accidentally modified the generated files manually.`nThen commit or undo the changes to generated files." -ForegroundColor Red
        exit
    }
}

# Delete all generated files
Get-ChildItem -Path $generatedFolder | Remove-Item

# For each *.template.md file in the docs\templates folder
# run the mermaid cli tool against it and output to the docs\generated folder
Get-ChildItem -Path $templatesFolder -Name -Include *.template.md | ForEach-Object {
    
    $rootFileName = $_ -ireplace '.template.md', ''
    $outputFileName = $rootFileName + '.md'

    # Create the generated .md file with .svg images for the mermaid charts
    mmdc -i $templatesFolder\$_ -o $generatedFolder\$outputFileName

    # Because we are unable to directly generate a .md file with .png files
    # we will generate the pngs and then replace the references in the generated .md file
    # see https://github.com/mermaid-js/mermaid-cli/issues/248
    $pngOutputFileName = $rootFileName + '.png'

    # Create png images for the mermaid charts
    mmdc -i $templatesFolder\$_ -o $generatedFolder\$pngOutputFileName

    # Load generated .md file into a string
    $generatedFileContent = Get-Content -Path $generatedFolder\$outputFileName
    # Replace .svg references with .png references
    $correctedFileContent = $generatedFileContent -replace "($rootFileName[-]\d*.)svg", '$1png'
    # Save corrected string back to file
    $correctedFileContent | Set-Content -Path $generatedFolder\$outputFileName

    # Delete unnecessary svg files
    Get-ChildItem -Path $generatedFolder\$rootFileName*.svg | Remove-Item
}

Set-Location $currentDir

ITNOA

Thanks, a lot!

Fantastic :)