platyPS - A PowerShell Help Generator

platyPS is an open source project that is designed to generate Markdown and MAML help files for PowerShell Modules and scripts.

Yesterday, Sergei Vorobev of the PowerShell Team published platyPS v 0.4.0 to the PowerShell Gallery. There have been some significant changes in the latest version, and the project is coming along very nicely.

Here are some of the major changes in v 0.4.0:

0.4.0

• Schema 2.0.0
• Layout of generated files - one file per cmdlet.
• Cmdlets renamed: platyPS prefix removed from the names.
• Removed APIs:
  • Get-ModuleFromMaml
  • New-MarkdownHelp always produces one md file per cmdlet in -OutputFolder.
• New APIs:
  • New-ExternalHelpCab - create updatable help Cab files.
  • Get-MarkdownMetadata - get a hashtable with yaml metadata (new in schema 2.0.0) from the markdown file
  • Update-MarkdownHelp, Update-MarkdownHelpModule - update your markdown with actual parameters metadata using reflection.
  • Update-MarkdowhHelpSchema - migrate from schema version 1.0.0 to schema version 2.0.0
  • Get-HelpPreview - get preview of help from Maml file. Returns help objects.
• Tab-completion support by @dotps1
  • Requires PS v5 or TabExpansionPlusPlus
  • Provides complitions for module names in New-ExternalHelp -Module <Tab>

The concept of this project is just great. Not only because MAML is ridiculous to read/edit, but mainly because of how popular markdown is becoming. Its easy to read/edit, and its very widly accepted.
This page was written in markdown, and is converted on the fly to html via jekyll.

I personally like online help, and by online I mean I like a project site, with a wiki I can reference. Don’t get me wrong, Get-Help is awesome, but I prefer to have a web page open, and reference that. So, based on this concept, platyPS will make creating online project wiki’s extremely easy. I have a project site for the WinSCP module I have created and maintained, and the Cmdlets wiki is all written in markdown, and rendered with Jekyll. Now, the schema of that markdown does not match the schema of platyPS, as I made the WinSCP site before discovering the platyPS project, but I had to type all of the markdown by hand which as you can imagine was very cumbersome. But, platyPS will take care of all the heavy lifting for you. So, you will only have to fill in the Synopsis, Description, Examples, and any misc Notes or Links you may want to use. So, I am hoping to write an ‘Integration’ of sorts that will use platyPS to do 90% of the work, but still have the ‘look and feel’ of my current schema. And the best part is you will be able to create you MAML help from the markdown with the New-ExternalHelp cmdlet!