PlatyPS is the primary tool for creating the PowerShell help displayed using Get-Help. PowerShell help files are stored in an XML format known as Microsoft Assistance Markup Language (MAML). Prior to PlatyPS, the help files were hand authored using complex tool chains. Markdown is widely used in the open source community, supported by many editors including Visual Studio Code, and easier to author. PlatyPS simplifies the process by allowing you to write the help files in Markdown and then converted to MAML.

Announcing Microsoft.PowerShell.PlatyPS

We’re pleased to announce the release of Microsoft.PowerShell.PlatyPS 1.0.0-Preview1. With this release, there are two versions of PlatyPS.

• platyPS v0.14.2 is the current version of PlatyPS that’s used to create PowerShell help files in Markdown format.
• Microsoft.PowerShell.PlatyPS is the new version of PlatyPS that includes several improvements:
  • Provides a more accurate description of a PowerShell cmdlet and its parameters
  • Increased performance – processes 1000s of Markdown files in seconds
  • Creates an object model of the help file that you can manipulate in memory
  • Provides cmdlets that you can chain together to perform complex operations

Our main goal for this release is to address long standing issues, add more schema driven features, and improve validity checking along with performance. This release is a substantial rewrite with all new cmdlets. If you have scripts that use the older version of PlatyPS, you must rewrite them to use the new cmdlets.

In this Preview release, we focused on:

• Re-write in C# leveraging markdig for parsing Markdown.
• New Markdown schema that includes all elements needed for Get-Help, plus information that was previously unavailable.
• The new cmdlets produce objects, supporting chaining cmdlets for complex operations.
• Full serialization to YAML to support our publishing pipeline.
• Automatic conversion of existing Markdown to the new object model.
• Export of the object model to Markdown, Yaml, and MAML.
• The module contains the following cmdlets:
  • Compare-CommandHelp
  • Export-MamlCommandHelp
  • Export-MarkdownCommandHelp
  • Export-MarkdownModuleFile
  • Export-YamlCommandHelp
  • Export-YamlModuleFile
  • Import-MamlHelp
  • Import-MarkdownCommandHelp
  • Import-MarkdownModuleFile
  • Import-YamlCommandHelp
  • Import-YamlModuleFile
  • New-CommandHelp
  • New-MarkdownCommandHelp
  • New-UpdateableHelp
  • Test-MarkdownCommandHelp
  • Update-CommandHelp
  • Update-MarkdownCommandHelp

Microsoft.PowerShell.PlatyPS runs on:

• Windows PowerShell 5.1+
• PowerShell 7+ on Windows, Linux, and macOS

Installing Microsoft.PowerShell.PlatyPS

To begin working with Microsoft.PowerShell.PlatyPS 1.0.0 Preview1, download and install the module from PSGallery.

Install-PSResource -Name Microsoft.PowerShell.PlatyPS -Prerelease

Documentation to get started

For the preview1 release, the cmdlet reference is available at Microsoft.PowerShell.PlatyPS. For an example of how to use the new cmdlets, see Example #1 in New-MarkdownCommandHelp.

Call to action

Our goal is to make it easier for you to update and maintain PowerShell help files. We value your feedback. Stop by our GitHub repository and let us know of any issues you find.

Jason Helmick

Sr. Product Manager, PowerShell