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 in the GitHub repository at
Microsoft.PowerShell.PlatyPS. We’re working on publishing the documentation to the Learn
platform before the next release.
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
The post Announcing Microsoft.PowerShell.PlatyPS 1.0.0-Preview1 appeared first on PowerShell Team.