PowerShell/docs/convert-ps2md.md

convert-ps2md.ps1

This PowerShell script converts the comment-based help of a PowerShell script to Markdown.

Parameters

PS> ./convert-ps2md.ps1 [[-filename] <String>] [<CommonParameters>]

-filename <String>
    Specifies the path to the PowerShell script
    
    Required?                    false
    Position?                    1
    Default value                
    Accept pipeline input?       false
    Accept wildcard characters?  false

[<CommonParameters>]
    This script supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, 
    WarningVariable, OutBuffer, PipelineVariable, and OutVariable.

Example

PS> ./convert-ps2md.ps1 myscript.ps1

Notes

Author: Markus Fleschutz | License: CC0

Related Links

https://github.com/fleschutz/PowerShell

Script Content

<#
.SYNOPSIS
	Converts a PowerShell script to Markdown
.DESCRIPTION
	This PowerShell script converts the comment-based help of a PowerShell script to Markdown.
.PARAMETER filename
	Specifies the path to the PowerShell script
.EXAMPLE
	PS> ./convert-ps2md.ps1 myscript.ps1
.LINK
	https://github.com/fleschutz/PowerShell
.NOTES
	Author: Markus Fleschutz | License: CC0
#>

param([string]$filename = "")

function EncodePartOfHtml { param([string]$Value)
    ($Value -replace '<', '&lt;') -replace '>', '&gt;'
}

function GetCode { param($Example)
    $codeAndRemarks = (($Example | Out-String) -replace ($Example.title), '').Trim() -split "`r`n"

    $code = New-Object "System.Collections.Generic.List[string]"
    for ($i = 0; $i -lt $codeAndRemarks.Length; $i++) {
        if ($codeAndRemarks[$i] -eq 'DESCRIPTION' -and $codeAndRemarks[$i + 1] -eq '-----------') { break }
        if ($codeAndRemarks[$i] -eq '' -and $codeAndRemarks[$i + 1] -eq '') { continue }
        if (1 -le $i -and $i -le 2) { continue }
    	$codeAndRemarks[$i] = ($codeAndRemarks[$i] | Out-String) -replace "PS>","PS> "
        $code.Add($codeAndRemarks[$i])
    }

    $code -join "`r`n"
}

function GetRemark { param($Example)
    $codeAndRemarks = (($Example | Out-String) -replace ($Example.title), '').Trim() -split "`r`n"

    $isSkipped = $false
    $remark = New-Object "System.Collections.Generic.List[string]"
    for ($i = 0; $i -lt $codeAndRemarks.Length; $i++) {
        if (!$isSkipped -and $codeAndRemarks[$i - 2] -ne 'DESCRIPTION' -and $codeAndRemarks[$i - 1] -ne '-----------') {
            continue
        }
        $isSkipped = $true
        $remark.Add($codeAndRemarks[$i])
    }

    $remark -join "`r`n"
}

try {
	if ($filename -eq "") { $filename = Read-Host "Enter path to PowerShell script" }
	$ScriptName = (Get-Item "$filename").Name

	$full = Get-Help $filename -Full 

	"*$($ScriptName)*"
	"================"

	$Description = ($full.description | Out-String).Trim()
	if ($Description -ne "") {
		""
		"$Description"
	} else {
		""
		"$($full.Synopsis)"
	}
	""
	"Parameters"
	"----------"
	"``````powershell"
	$Syntax = (($full.syntax | Out-String) -replace "`r`n", "`r`n").Trim()
	$Syntax = (($Syntax | Out-String) -replace "/home/mf/Repos/PowerShell/scripts/", "PS> ./")
	if ($Syntax -ne "") {
		"$Syntax"
	}

	foreach($parameter in $full.parameters.parameter) {
		"$(((($parameter | Out-String).Trim() -split "`r`n")[-5..-1] | % { $_.Trim() }) -join "`r`n")"
		""
	}
	"[<CommonParameters>]"
	"    This script supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, "
	"    WarningVariable, OutBuffer, PipelineVariable, and OutVariable."
	"``````"

	foreach($input in $full.inputTypes.inputType) {
		""
		"Inputs"
		"------"
		"$($input.type.name)"
	}

	foreach($output in $full.outputTypes.outputType) {
		""
		"Outputs"
		"-------"
		"$($output.type.name)"
	}

	foreach($example in $full.examples.example) {
		""
		"Example"
		"-------"
		"``````powershell"
		"$(GetCode $example)"
		"``````"
	}

	$Notes = ($full.alertSet.alert | Out-String).Trim()
	if ($Notes -ne "") {
		""
		"Notes"
		"-----"
		"$Notes"
	}

	$Links = ($full.relatedlinks | Out-String).Trim()
	if ($Links -ne "") {
		""
		"Related Links"
		"-------------"
		"$Links"
	}

	""
	"Script Content"
	"--------------"
	"``````powershell"
	$Lines = Get-Content -path "$filename"
        foreach($Line in $Lines) {
		"$Line"
	}
	"``````"
	""
	$now = [datetime]::Now
	"*(generated by convert-ps2md.ps1 using the comment-based help of $ScriptName as of $now)*"
} catch {
	"⚠️ Error in line $($_.InvocationInfo.ScriptLineNumber): $($Error[0])"
        exit 1
}

(generated by convert-ps2md.ps1 using the comment-based help of convert-ps2md.ps1 as of 12/16/2023 10:12:20)