Fix pandoc version regex and write error exception

[kborowinski]

PR Summary

This PR improves robustness in tools/build-updatedhelp.ps1 by fixing Pandoc version detection for never versions and by fixing the PlatyPS exception handling.

• Fixes Pandoc version parsing when pandoc --version doesn’t include pandoc.exe:

InvalidOperation: D:\DEVELOPMENT\PowerShellHelp\tools\build-updatedhelp.ps1:40
Line |
  40 |      $version = (& $pandoc.Source --version | Select-String -Pattern ' …
     |      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | You cannot call a method on a null-valued expression.
Write-Error: D:\DEVELOPMENT\PowerShellHelp\tools\build-updatedhelp.ps1:168

• Fixes PlatyPS error reporting by logging the actual exception $_.Exception instead of the full error record.

Line |
 168 |  … ror -Message "PlatyPS failure: $ModuleName -- $Version" -Exception $_
     |                                                                       ~~
     | Cannot bind parameter 'Exception'. Cannot convert the "Exception calling "GetYamlMetadata" with "1" argument(s): "Invalid yaml: expected simple key-value pairs"" value of type
     | "System.Management.Automation.ErrorRecord" to type "System.Exception".

    Directory: D:\DEVELOPMENT\PowerShellHelp\maml\7.5\Microsoft.PowerShell.Archive

This is example of pandoc --version output from latest version of pandoc:

pandoc 3.8.3
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: C:\Users\Bukem\AppData\Roaming\pandoc
Copyright (C) 2006-2025 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

PR Checklist

• Descriptive Title: This PR's title is a synopsis of the changes it proposes.
• Summary: This PR's summary describes the scope and intent of the change.
• Contributor's Guide: I have read the contributor's guide.
• Style: This PR adheres to the style guide.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 248a007:

✅ Validation status: passed

File	Status	Preview URL	Details
tools/build-updatedhelp.ps1	✅Succeeded

For more details, please refer to the build report.

[sdwheeler]

Thanks for the update. We don't really use this anymore. It may be deleted at some point. I have a better version that I need to publish at some point. But for now, I will take this change.

[kborowinski]

@sdwheeler:
I’m very interested in the newer version whenever you’re able to publish it. I’m currently building the help locally and distributing it internally for my organization (disconnected on-prem network), and keeping that pipeline alive is important for us.
I’m responsible for PowerShell in the org updates, module rollouts, and help content, so having an up-to-date, publishable help makes a real difference on our side.

[sdwheeler]

@sdwheeler: I’m very interested in the newer version whenever you’re able to publish it.

This is the improved version of the code to convert about_*.md files. It needs a version check for Pandoc. But the main difference is that it creates properly formatted about_*.help.txt files.

function Invoke-Pandoc {

    [CmdletBinding()]
    [OutputType([void])]
    param(
        [Parameter(Mandatory)]
        [string[]]$Path,
        [string]$OutputPath = '.',
        [switch]$Recurse
    )

    # Initialize recurse parameter if not specified
    if (-not $PSBoundParameters.ContainsKey('Recurse')) {
        $Recurse = $false
    }

    # Ensure pandoc is available
    $pandocExe = Get-Command pandoc.exe
    if ($null -eq $pandocExe) {
        Write-Error 'pandoc.exe not found in PATH. See https://pandoc.org/installing.html'
        return
    }

    # Define Pandoc template, filter, and arguments
    $aboutTemplate = @(
        'TOPIC'
        '    $title$'
        ''
        'SYNOPSIS'
        '    $description$'
        ''
        '$body$'
    ) -join [Environment]::NewLine

    $luaFilter = @(
        'function Header(elem)'
        '    local text = pandoc.utils.stringify(elem.content)'
        '    local underline_char = { "=", "=" }'
        '    local level = elem.level'
        '    local underline = string.rep(underline_char[level] or "-", #text)'
        '    return pandoc.Para{pandoc.Str(text), pandoc.LineBreak(), pandoc.Str(underline)}'
        'end'
    ) -join [Environment]::NewLine

    $templatePath = "$env:TEMP\pandoc-template.txt"
    $luaFilterPath = "$env:TEMP\pandoc-filter.lua"
    $pandocArgs = @(
        '--from=gfm',
        '--to=plain+multiline_tables-yaml_metadata_block',
        "--lua-filter=$luaFilterPath",
        "--template=$templatePath",
        '--columns=79',
        '--quiet'
    )
    Write-Verbose "Pandoc: $($pandocExe.Source)"
    Write-Verbose "Args: $($pandocArgs -join ' ')"

    # Create Pandoc assets
    $aboutTemplate | Out-File $templatePath -Encoding utf8
    $luaFilter | Out-File $luaFilterPath -Encoding utf8

    # Process files
    $files = Get-ChildItem $Path -Recurse:$Recurse
    foreach ($f in $files) {
        $outfile = Join-Path $OutputPath "$($f.BaseName).help.txt"
        Write-Verbose "Converting $($f.Name) to $outfile"

        $metadata = Get-Metadata -Path $f
        if ($null -eq $metadata) {
            Write-Error "No metadata found in $($f.Name)"
            continue # Skip to next file
        }
        if (-not $metadata.Contains('title') -or $metadata.title -eq '') {
            Write-Error "Missing metadata.title in $($f.Name)"
            continue # Skip to next file
        }
        if (-not $metadata.Contains('description') -or $metadata.description -eq '') {
            Write-Error "Missing metadata.description in $($f.Name)"
            continue # Skip to next file
        }

        # Remove H1 from markdown content
        $markdown = (Get-Content $f -Raw) -replace "# $($metadata.title)\r?\n", ''

        $markdown | & $pandocExe @pandocArgs | Out-File $outfile -Encoding utf8
    }

}