PlatyPS is the primary tool for creating the PowerShell help displayed using Get-Help.
What is PlatyPS
PowerShell external help files have been authored by hand or using complex tool chains and stored as
MAML XML for use as console help.
MAML is cumbersome to edit by
hand, and common tools and editors don’t support it for complex scenarios like they do with
markdown. Markdown is adopted widely by
Open Source, supported by many editors including
Visual Studio Code, and with minimal rules, easier to author.
PlatyPS is provided as a solution to allow documenting PowerShell help in any editor or tool
that supports markdown.
PlatyPS handles PowerShell documentation for complex scenarios (e.g. very large, closed source,
and/or C#/binary modules) where it may be desirable to have documentation abstracted away from the
codebase. PlatyPS does not need source access to generate documentation. PlatyPS solves this
scenario today at Microsoft by delivering
updatable help
files for PowerShell, SCCM, Windows, and other supported modules. Module authors may also use
PlatyPS to create the help that ships with their modules.
Announcing PlatyPS 2.0-Preview1
We are pleased to announce the release of PlatyPS 2.0.0-Preview1.
Our main goal for the 2.0.0 release is to maintain compatibility while fixing long standing issues.
We are re-writing PlatyPS in C# to leverage the existing markdown C# library allowing us to
address many of the open issues and make schema improvements recommended by the community. The main
functionality of PlatyPS remains unchanged except for community suggested bug fixes and
enhancements. We do expect a few necessary breaking changes in future previews.
In this Preview release, we focused on:
- re-write in C# leveraging Markdig for parsing markdown.
- updated
New-MarkdownHelp - updated
Get-MarkdownMetadata
Future preview releases will include more performance improvements and cmdlet updates.
What’s supported
PlatyPS 2.0.0-Preview1 is currently available for download from the PowerShell Gallery.
Supported PowerShell versions for PlatyPS 2.0.0:
- Windows PowerShell 5.1+
- PowerShell 7.0+
Installing PlatyPS
To begin working with PlatyPS 2.0 Preview1, download and install the PlatyPS module from PSGallery.
Install-Module PlatyPS -AllowPrereleaseMarkdown Schema Updates
Markdown is designed to be human-readable, without rendering. This makes writing and editing easy
and efficient. Many editors support markdown including Visual Studio Code. PlatyPS expects
markdown to be authored in a particular way. We have defined a schema to determine how parameters
are described, where scripts examples are shown, and so on.
The schema closely resembles the existing output format of the Get-Help cmdlet in PowerShell. If
you break the schema in your markdown, you will receive error messages.
For more information about the planned changes, see the
PlatyPS Design Specification.
Note, this is a draft specification subject to change.
Documentation to get started
For information about PlatyPS including cmdlet reference, see PlatypS
For additional information and examples of working with PlatyPS, see
Create XML-based help using PlatyPS.
Call to action
Our goal is to make it easier to update and maintain module/cmdlet help files. We value your ideas
and feedback. Stop by our GitHub repository and let us know of any issues or features you would like
added.
For more information about PlatyPS issues and features, see:
PlatyPS on GitHub
Jason Helmick
Program Manager, PowerShell
The post Announcing PlatyPS 2.0.0-Preview1 appeared first on PowerShell Team.