platyPS
A PowerShell module for authoring external help files in Markdown and converting them to MAML format.
What is platyPS?
PlatyPS is a PowerShell module developed by Microsoft that simplifies the creation of PowerShell help content. It allows authors to write documentation in Markdown, a widely supported and easier-to-use format, and converts it to the Microsoft Assistance Markup Language (MAML) XML format used by PowerShell's `Get-Help` command and Microsoft Learn documentation.
PowerShell module developers and technical writers who need to create or maintain help documentation for PowerShell cmdlets, especially those contributing to Microsoft's official PowerShell documentation on Microsoft Learn.
Developers choose PlatyPS because it replaces complex XML authoring with Markdown, leveraging industry-standard tools like Visual Studio Code, and provides high-performance processing with accurate cmdlet representation through a C# rewrite using the Markdig library.
Overview
Write PowerShell External Help in Markdown
Use Cases
Best For
- Creating PowerShell help files for custom modules without dealing with MAML XML directly.
- Contributing to Microsoft's official PowerShell documentation on Microsoft Learn.
- Automating the generation of help content for large PowerShell codebases with thousands of cmdlets.
- Maintaining consistent and up-to-date help documentation across PowerShell 5.1+ and PowerShell 7+ on Windows, Linux, and macOS.
- Integrating help authoring into CI/CD pipelines due to its fast processing of Markdown files.
- Leveraging an object model for programmatic manipulation and chaining of help file operations.
Not Ideal For
- Projects that require documentation for non-PowerShell technologies, as PlatyPS is specifically designed for PowerShell help and cannot generate output for other frameworks.
- Small-scale scripting scenarios where help content is minimal and manually writing MAML XML might be simpler than setting up and learning PlatyPS.
- Teams using alternative documentation tools like Sphinx or DocFX that are already integrated into their workflow and don't require MAML output.
- Environments needing real-time, dynamic help generation during PowerShell runtime, since PlatyPS is optimized for batch processing of static Markdown files.
Pros & Cons
Pros
Allows writing help in Markdown instead of complex MAML XML, supported by editors like Visual Studio Code, making documentation more accessible and maintainable for developers.
Rebuilt in C# with the Markdig library, it processes thousands of Markdown files in seconds, enabling efficient handling of large PowerShell codebases as highlighted in the README.
Provides more precise descriptions of PowerShell cmdlets and parameters, including previously unavailable information, ensuring help content aligns closely with actual cmdlet behavior.
Creates a manipulatable object model of help files, enabling complex operations through cmdlet chaining for advanced automation and integration into scripts.
Cons
Contributing or building from source requires specific prerequisites like PS7, .NET 8 SDK, and Pester 4.x (not 5.x), adding overhead for developers who want to customize or extend the tool.
The project maintains a legacy v1 branch that is no longer actively maintained, which can cause confusion and migration challenges for users of older versions.
Exclusively designed for PowerShell help documentation, making it unsuitable for projects that need cross-platform or multi-language documentation solutions.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.