Microsoft.PowerShell.PlatyPS: authoring Get-Help content in Markdown

Get-Help content is MAML, and MAML is painful to write by hand

The problem PlatyPS solves starts with a file format decision made long before it. PowerShell help files are stored as Microsoft Assistance Markup Language, an XML format. That format is what Get-Help reads and what ships inside module packages, and writing it by hand is unpleasant because it is XML describing a document, with the descriptions, parameters and examples nested inside elements rather than sitting in readable text.

PlatyPS changes the authoring side only. You write the help in Markdown, then convert to MAML. The reasoning given is practical rather than aesthetic: Markdown is widely used in the software industry, supported by many editors including Visual Studio Code, and easier to author than XML.

The scope is narrower than the name suggests. This is a help authoring pipeline, not a converter between general markup formats. It knows about cmdlet structure, parameters, examples and the specific MAML schema that PowerShell expects. Feed it an arbitrary Markdown document and there is nothing for it to produce.

The provenance is the strongest argument for using it. The README states that PlatyPS is the tool Microsoft uses to create the PowerShell content you get from Get-Help and to build the content published as PowerShell documentation on Microsoft Learn. When a tool used internally to build a product's own documentation is released, the compatibility with that documentation pipeline is the feature.

A C# rewrite on markdig, with an object model you can script against

The current version was rewritten in C#, which is the main structural difference from what came before. The README lists several improvements that follow from that rewrite.

Markdown parsing is delegated to markdig, and the note about which library it is matters: markdig is the same library Microsoft Learn uses to render Markdown. That is a deliberate choice to align the parser with the renderer, so what you write and what the documentation site shows come from the same parsing rules.

The module creates an object model of the help file that you can manipulate, and supports chaining cmdlets for complex operations. For a documentation pipeline that means you can load a set of Markdown files, transform them programmatically, and write them back out, rather than only converting files one at a time.

The content fidelity also improved. The README says the rewrite provides a more accurate description of a PowerShell cmdlet and its parameters, and includes information that was previously unavailable. That last point is the one to weigh: if you are migrating help files written for the old tool, the new version may surface metadata that was previously dropped, which changes the output rather than merely the tooling.

The performance claim is about batches. The README says the tool processes thousands of Markdown files in seconds, which is what makes the object model and the chaining useful in a repository sized like a PowerShell module collection.

Install from the Gallery, then create, edit, test and publish

Installation is a single command from PSGallery:

Install-PSResource -Name Microsoft.PowerShell.PlatyPS

The module runs on Windows PowerShell 5.1 and later, and on PowerShell 7 and later on Windows, Linux and macOS. That second platform list is worth noting because a build and documentation pipeline that runs on Linux CI is now possible, and the module itself is a PowerShell Gallery package rather than something you compile.

Creating help files is described as a multi-step process with four stages. You create new or update existing Markdown help files, then edit the Markdown help to add descriptions and examples, then test the Markdown help to ensure the files render correctly, and finally convert and publish the help files. Each of those stages has its own documentation page on Microsoft Learn, linked from the README.

The order is the interesting part. Testing comes before publishing, and it comes after editing. That sequence means a broken help file is caught while it is still Markdown, which is where a human can read the error, rather than after conversion when the problem is nested XML. The step-by-step guidance lives on Microsoft Learn under the platyps section of the PowerShell utility modules documentation.

The published documentation is the reference for exact cmdlet names in each step, since the README deliberately links out rather than restating the commands for each phase.

Two package names, two branches, and one of them is frozen

The repository layout carries a migration story that anyone with an existing platyPS setup needs to understand.

The main branch contains the source for the new version, named Microsoft.PowerShell.PlatyPS, and that is the current supported version, listed in the PowerShell Gallery under the same name. The v1 branch holds the legacy version named platyPS, and the README says plainly that this version is no longer actively maintained, though it remains available for reference and legacy support. Its last version is 0.14.2, published in the Gallery as platyPS.

So there are two packages in the Gallery with confusingly similar names, and only one of them receives updates. If you have an existing pipeline that installs platyPS, that package is not going to change behaviour or gain features, and moving to Microsoft.PowerShell.PlatyPS is a deliberate migration rather than an in-place upgrade.

The repository structure is a standard .NET layout with a twist for PowerShell module builds. The src directory holds the module source, test holds the test files used to validate the code at build time, tools holds the tools used to build the module, and docs contains design documentation for the PlatyPS project. There is a platyPS.sln solution file, a build.ps1 script, a global.json, a nuget.config, a CHANGELOG.md, a ThirdPartyNotices.txt file and a CODE_OF_CONDUCT.md.

The licence is MIT.

Building it yourself needs PS7, .NET 8 and Pester 4

Contributors can build the module from source, and the prerequisites are specific enough to trip people up in two places.

For the build you need PS7 and the .NET 8 SDK. For the tests you need Pester 4.x, and the README is explicit that Pester 5.x is not supported. That restriction is the kind of detail that turns into an afternoon of confusion if you assume the current Pester works, since the module's own test suite is run at build time from the test directory.

The build command is a single script run from the root of the repository:

.\build.ps1 -Clean

The -Clean flag is the normal invocation given in the README, which suggests a fresh build rather than an incremental one.

The presence of a .config directory, a .pipelines directory, a .ci directory and a .github directory at the top level tells you the project has both its own pipeline definitions and GitHub side by them, and the .vscode directory suggests the contributors work in Visual Studio Code.

Building from source only matters if you are changing the module. For using it, the Gallery install is the whole story, and the docs folder is the place to look for the design rationale when you want to understand why a conversion behaves the way it does.

Where PlatyPS is the wrong tool

The first wrong-tool case is expecting a general MAML converter. The tool is built around the PowerShell help schema. There is no documented mode that takes arbitrary MAML input and re-emits it, and no documented mode that converts Markdown to some other target. If your problem is help files for PowerShell, this is the tool. If your problem is XML documents in general, it is not.

The second is a workflow that cannot use the four-stage process. The documented flow assumes you can author Markdown, test the result, and then publish. A pipeline that has no place to test the help before it ships will end up skipping the stage that catches most errors, and the README does not describe an alternative validation route.

The third is the legacy package. If your build scripts pin platyPS, the version you have will keep behaving exactly as it does, with no fixes and no new capability, because the README states that branch is no longer actively maintained and stopped at 0.14.2. Staying on it is a valid choice, but it should be a choice.

On maintenance, the supported line is doing fine. The repository is not archived, the last push was on 2026-09-14, and three releases of Microsoft.PowerShell.PlatyPS shipped in 2026, with v1.0.1 on 2025-07-30 followed by v1.0.2 on 2026-07-20 and v1.0.3 on 2026-07-23. Two patch releases two days apart in July suggest a release process that is being used.

Editorial conclusion

Microsoft.PowerShell.PlatyPS suits anyone who ships a PowerShell module and wants help files that are writable in Markdown and testable before publishing, and it does not suit a team looking for a general Markdown to MAML converter for arbitrary XML. Before you upgrade from the older platyPS package, note that the current module is Microsoft.PowerShell.PlatyPS on the main branch while the legacy platyPS line lives on the v1 branch, is no longer actively maintained and stopped at 0.14.2, so plan the rename rather than assuming the old module will keep working.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. PowerShell/platyPS on GitHub
4. README
5. Releases