PlatyPS Workflow

1. Import the module being documented

   Import-Module .\ManageIssues.psd1
   

2. Create new markdown files (cmdlet and module)

   $newMarkdownHelpSplat = @{
       Module = 'ManageIssues'
       AlphabeticParamsOrder = $true
       UseFullTypeName = $true
       OutputFolder = '.\docs'
       WithModulePage = $true
   }
   New-MarkdownHelp @newMarkdownHelpSplat
   

   PlatyPS creates placeholders for you to fill in metadata, descriptions, and examples. The PowerShell help system also allows for plain-text conceptual help files (about topics). PlatyPS includes the New-MarkdownAboutHelp cmdlet to create a structured Markdown template for a new about file, but you must convert the markdown to about_*.help.txt files manually.

3. Edit markdown files to add descriptions, examples, links, notes, etc.

   Metadata in <Module>.md and <Cmdlet-Name>.md files is used when compiling the MAML files. The markdown files aren’t used directly by the help system. It’s important that the metadata is correct for the help system to work properly.

4. Compile markdown into MAML

   $newExternalHelpSplat = @{
       Path = '.\docs'
       OutputPath = '.\help'
   }
   New-ExternalHelp @newExternalHelpSplat
   

5. Test the MAML

   Get-HelpPreview -Path .\help\ManageIssues-help.xml
   

6. Create the module help CAB/ZIP and HelpInfo XML files.

   mkdir .\help\cab
   $newExternalHelpCabSplat = @{
       CabFilesFolder = '.\help'
       LandingPagePath = '.\docs\ManageIssues.md'
       OutputFolder = '.\help\cab'
   }
   New-ExternalHelpCab @newExternalHelpCabSplat
   

   The CabFilesFolder location must contain the MAML files and any about_*.help.txt files that you want to publish for the module. For a script-based module, there is usually only one MAML file. However, if your module contains submodules or has cmdlets in compiled assemblies, there will be multiple MAML files.

7. Publish CAB and XML to web service

   Copy the files to the web server.

For more information, see Create XML-based help using PlatyPS.

Previous