Announcing Microsoft.PowerShell.PlatyPS 1.0.0-Preview1

This post was originally published on this site

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.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.