Powershell-Copilot-Standards platyps.instructions.md

PowerShell Help Documentation with PlatyPS

Every module generates its command help with Microsoft.PowerShell.PlatyPS and ships compiled MAML external help. Markdown under docs/ is the source you edit; en-US/<ModuleName>-Help.xml is the build output that Get-Help actually reads.

Use the Supported Module

Target version: Microsoft.PowerShell.PlatyPS 1.0.3+.

Install-PSResource -Name Microsoft.PowerShell.PlatyPS

The original platyPS v0.14.2 is no longer supported. It is a different module with different cmdlet names, and its Markdown uses an older schema. Never generate platyPS 0.14 commands:

Do not use (platyPS 0.14.2)	Use instead (Microsoft.PowerShell.PlatyPS 1.x)
New-MarkdownHelp	New-MarkdownCommandHelp
Update-MarkdownHelp	Update-MarkdownCommandHelp
New-ExternalHelp	Export-MamlCommandHelp
New-ExternalHelpCab	New-HelpCabinetFile
Get-HelpPreview	Show-HelpPreview
Update-MarkdownHelpModule	Update-MarkdownModuleFile

Update-MarkdownCommandHelp can read 0.14.2-era Markdown and rewrite it in the current schema, so migrating an existing project does not mean starting the documentation over. See Migrating existing docs.

Authoring Model

Markdown is the source of truth for public command help. Comment-based help seeds it once, then the Markdown is what you edit. The seeding only works if .EXTERNALHELP is added after the first generation — see that ordering rule.

Public/Get-Thing.ps1
  |  <# .EXTERNALHELP ModuleName-Help.xml      <-- required; see below
  |     .SYNOPSIS  one line for source readers #>
  |
  |  New-MarkdownCommandHelp        (once, at first generation)
  |  Update-MarkdownCommandHelp     (every time the signature changes)
  v
docs/ModuleName/Get-Thing.md        <-- EDIT HERE. Canonical. Committed.
docs/ModuleName/ModuleName.md       <-- module page. Committed.
  |
  |  Export-MamlCommandHelp         (build step)
  v
en-US/ModuleName-Help.xml           <-- build output. What Get-Help reads.