More Platyps Production
In this issue:
We've started exploring the new Platyps module from Microsoft. This is what you should be using to generate help documentation for your PowerShell commands and modules. The new version is a complete rewrite from the now legacy Platyps module. To follow along you will need to install the Microsoft.PowerShell.Platyps module from the PowerShell Gallery.
Last time, I introduced the module, it's paradigm, and how to use the module commands to create help documentation for a stand-alone command. I want to show a few more things with a stand-alone function. You can use the same techniques when working with commands in your module.
Updating Help
Last time I created a markdown help file for a stand-alone command. As often happens, commands get updated. You might add (or remove) parameters. You might add aliases, or change parameter attributes. Here's a slightly updated version of the function I used last time.
function Get-OSInfo {
[cmdletbinding()]
[OutputType('OperatingSystemInfo','String')]
[Alias("goi")]
param(
[Parameter(
Position = 0,
ValueFromPipeline,
ValueFromPipelineByPropertyName,
HelpMessage = "Specify the name of a computer to query."
)]
[Alias('cn')]
[ValidateNotNullOrEmpty()]
[string[]]$Computername = $env:computername,
[Parameter(HelpMessage = "Return the OS name only.")]
[Alias("no")]
[switch]$NameOnly
)
begin {
Write-Verbose "[BEGIN ] Starting: $($MyInvocation.MyCommand)"
$paramHash = @{
ClassName = 'Win32_OperatingSystem'
ErrorAction = 'Stop'
}
} #begin
process {
foreach ($computer in $Computername) {
Write-Verbose "[PROCESS] Connecting to $Computer"
$paramHash.Computername = $Computer
try {
$data = Get-CimInstance @paramHash
if ($NameOnly) {
$data.caption
}
else {
[PSCustomObject]@{
PSTypename = 'OperatingSystemInfo'
Name = $data.Caption
Version = $data.Version
Architecture = $data.OSArchitecture
InstallDate = $data.InstallDate
Computername = $data.CSName
}
}
} #try
catch {
Write-Warning "Failed to retrieve information from $($computer.ToUpper()). $($_.Exception.Message)"
} #catch
} #Foreach
} #process
end {
Write-Verbose "[END ] Ending: $($MyInvocation.MyCommand)"
} #end
}
I will need to load this version into my PowerShell session before going any further.
The new Platyps module has a few update commands
PS C:\> Get-Command -module Microsoft.Powershell.Platyps -verb Update | Select Name
Name
----
Update-CommandHelp
Update-MarkdownCommandHelp
Update-MarkdownModuleFile
Updating Existing Markdown
I have the Markdown file I created last time from the CommandHelp object. That's what I want to update.
PS C:\> Get-Command Update-MarkdownCommandHelp -Syntax
Update-MarkdownCommandHelp [-Path] <string[]> [-NoBackup] [-PassThru] [-WhatIf] [-Confirm] [<commonparameters>]
Update-MarkdownCommandHelp -LiteralPath <string[]> [-NoBackup] [-PassThru] [-WhatIf] [-Confirm] [<commonparameters>]
I should be able to pass the path to the existing Markdown file.
Update-MarkdownCommandHelp -Path .\Get-OSInfo.md
I really like that by default you get a backup copy of the original file.
PS C:\Users...\platyps-v2\> dir *.bak
Directory: C:\Users\jeff\OneDrive\behind\2026\platyps-v2
Mode LastWriteTime Length Name
---- ------------- ------ ----
la--- 8/9/2026 10:54 AM 2138 Get-OSInfo.md.bak
I can now manually add any other edits to the file such as adding command Alias information. There is a section in the help document, but the commands don't seem to detect defined aliases. I seem to recall seeing an open issue on this topic.
