Create XML-based help using PlatyPS

Article
11/10/2023

When creating a PowerShell module, it's always recommended that you include detailed help for the cmdlets you create. If your cmdlets are implemented in compiled code, you must use the XML-based help. This XML format is known as the Microsoft Assistance Markup Language (MAML).

The legacy PowerShell SDK documentation covers the details of creating help for PowerShell cmdlets packaged into modules. However, PowerShell doesn't provide any tools for creating the XML-based help. The SDK documentation explains the structure of MAML help, but leaves you the task of creating the complex, and deeply nested, MAML content by hand.

This is where the PlatyPS module can help.

What is PlatyPS?

PlatyPS is an open-source tool that started as a hackathon project to make the creation and maintenance of MAML easier. PlatyPS documents the syntax of parameter sets and the individual parameters for each cmdlet in your module. PlatyPS creates structured Markdown files that contain the syntax information. It can't create descriptions or provide examples.

PlatyPS creates placeholders for you to fill in descriptions and examples. After adding the required information, PlatyPS compiles the Markdown files into MAML files. PowerShell's help system also allows for plain-text conceptual help files (about topics). PlatyPS has a cmdlet to create a structured Markdown template for a new about file, but these about_*.help.txt files must be maintained manually.

You can include the MAML and Text help files with your module. You can also use PlatyPS to compile the help files into a CAB package that can be hosted for updateable help.

Get started using PlatyPS

First you must install PlatyPS from the PowerShell Gallery.

# Install using PowerShellGet 2.x
Install-Module platyps -Force

# Install using PSResourceGet 1.x
Install-PSResource platyps -Force

After installing PlatyPS, import the module into your session.

Import-Module platyps

The following flowchart outlines the process for creating or updating PowerShell reference content.

The workflow for creating XML-based help using PlatyPS

Create Markdown content for a PowerShell module

Import your new module into the session. Repeat this step for each module you need to document.

Run the following command to import your modules:
```
Import-Module <your module name>
```
Use PlatyPS to generate Markdown files for your module page and all associated cmdlets within the module. Repeat this step for each module you need to document.
```
$OutputFolder = <output path>
$parameters = @{
    Module = <ModuleName>
    OutputFolder = $OutputFolder
    AlphabeticParamsOrder = $true
    WithModulePage = $true
    ExcludeDontShow = $true
    Encoding = [System.Text.Encoding]::UTF8
}
New-MarkdownHelp @parameters

New-MarkdownAboutHelp -OutputFolder $OutputFolder -AboutName "topic_name"
```
If the output folder doesn't exist, New-MarkdownHelp creates it. In this example, New-MarkdownHelp creates a Markdown file for each cmdlet in the module. It also creates the module page in a file named <ModuleName>.md. This module page contains a list of the cmdlets contained in the module and placeholders for the Synopsis description. The metadata in the module page comes from the module manifest and is used by PlatyPS to create the HelpInfo XML file (as explained below).

New-MarkdownAboutHelp creates a new about file named about_topic_name.md.

For more information, see New-MarkdownHelp and New-MarkdownAboutHelp.

Update existing Markdown content when the module changes

PlatyPS can also update existing Markdown files for a module. Use this step to update existing modules that have new cmdlets, new parameters, or parameters that have changed.

Import your new module into the session. Repeat this step for each module you need to document.

Run the following command to import your modules:
```
Import-Module <your module name>
```
Use PlatyPS to update Markdown files for your module landing page and all associated cmdlets within the module. Repeat this step for each module you need to document.
```
$parameters = @{
    Path = <folder with Markdown>
    RefreshModulePage = $true
    AlphabeticParamsOrder = $true
    UpdateInputOutput = $true
    ExcludeDontShow = $true
    LogPath = <path to store log file>
    Encoding = [System.Text.Encoding]::UTF8
}
Update-MarkdownHelpModule @parameters
```
Update-MarkdownHelpModule updates the cmdlet and module Markdown files in the specified folder. It doesn't update the about_*.md files. The module file (ModuleName.md) receives any new Synopsis text that has been added to the cmdlet files. Updates to cmdlet files include the following change:
- New parameter sets
- New parameters
- Updated parameter metadata
- Updated input and output type information
For more information, see Update-MarkdownHelpModule.

Edit the new or updated Markdown files

PlatyPS documents the syntax of the parameter sets and the individual parameters. It can't create descriptions or provide examples. The specific areas where content is needed are contained in curly braces. For example: {{ Fill in the Description }}

Markdown template showing the placeholders in VS Code

You need to add a synopsis, a description of the cmdlet, descriptions for each parameter, and at least one example.

For detailed information about writing PowerShell content, see the following articles:

Note

PlatyPS has a specific schema that's uses for cmdlet reference. That schema only allows certain Markdown blocks in specific sections of the document. If you put content in the wrong location, the PlatyPS build step fails. For more information, see the schema documentation in the PlatyPS repository. For a complete example of well-formed cmdlet reference, see Get-Item.

After providing the required content for each of your cmdlets, you need to make sure that you update the module landing page. Verify your module has the correct Module Guid and Download Help Link values in the YAML metadata of the <module-name>.md file. Add any missing metadata.

Also, you may notice that some cmdlets may be missing a Synopsis (short description). The following command updates the module landing page with your Synopsis description text. Open the module landing page to verify the descriptions.

Update-MarkdownHelpModule -Path <full path output folder> -RefreshModulePage

Now that you have entered all the content, you can create the MAML help files that are displayed by Get-Help in the PowerShell console.

Create the external help files

This step creates the MAML help files that are displayed by Get-Help in the PowerShell console.

To build the MAML files, run the following command:

New-ExternalHelp -Path <folder with MDs> -OutputPath <output help folder>

New-ExternalHelp converts all cmdlet Markdown files into one (or more) MAML files. About files are converted to plain-text files with the following name format: about_topic_name.help.txt. The Markdown content must meet the requirement of the PlatyPS schema. New-ExternalHelp exits with errors when the content doesn't follow the schema. You must edit the files to fix the schema violations.

Caution

PlatyPS does a poor job converting the about_*.md files to plain text. You must use very simple Markdown to get acceptable results. You may want to maintain the files in plain-text about_topic_name.help.txt format, rather than allowing PlatyPS to convert them.

Once this step is complete, you will see *-help.xml and about_*.help.txt files in the target output folder.

For more information, see New-ExternalHelp

Test the compiled help files

You can verify the content with the Get-HelpPreview cmdlet:

Get-HelpPreview -Path "<ModuleName>-Help.xml"

The cmdlet reads the compiled MAML file and outputs the content in the same format you would receive from Get-Help. This allows you to inspect the results to verify that the Markdown files compiled correctly and produce the desired results. If you find an error, re-edit the Markdown files and recompile the MAML.

Now you are ready to publish your help files.

Publishing your help

Now that you have compiled the Markdown files into PowerShell help files, you are ready to make the files available to users. There are two options for providing help in the PowerShell console.

Package the help files with the module
Create an updateable help package that users install with the Update-Help cmdlet

Packaging help with the module

The help files can be packaged with your module. See Writing Help for Modules for details of the folder structure. You should include the list of Help files in the value of the FileList key in the module manifest.

Creating an updateable help package

At a high level, the steps to create updateable help include:

Find an internet site to host your help files
Add a HelpInfoURI key to your module manifest
Create a HelpInfo XML file
Create CAB files
Upload your files

For more information, see Supporting Updateable Help: Step-by-step.

PlatyPS assists you with some of these steps.

The HelpInfoURI is a URL that points to location where your help files are hosted on the internet. This value is configured in the module manifest. Update-Help reads the module manifest to get this URL and download the updateable help content. This URL should only point to the folder location and not to individual files. Update-Help constructs the filenames to download based on other information from the module manifest and the HelpInfo XML file.

Important

The HelpInfoURI must end with a forward-slash character (/). Without that character, Update-Help can't construct the correct file paths to download the content. Also, most HTTP-based file services are case-sensitive. It's important that the module metadata in the HelpInfo XML file contains the proper letter case.

The New-ExternalHelp cmdlet creates the HelpInfo XML file in the output folder. The HelpInfo XML file is built using YAML metadata contained in the module Markdown files (ModuleName.md).

The New-ExternalHelpCab cmdlet creates ZIP and CAB files containing the MAML and about_*.help.txt files you compiled. CAB files are compatible with all versions of PowerShell. PowerShell 6 and higher can use ZIP files.

$helpCabParameters = @{
    CabFilesFolder = $MamlOutputFolder
    LandingPagePath = $LandingPage
    OutputFolder = $CabOutputFolder
}
New-ExternalHelpCab @helpCabParameters

After creating the ZIP and CAB files, upload the ZIP, CAB, and HelpInfo XML files to your HTTP file server. Put the files in the location indicated by the HelpInfoURI.

For more information, see New-ExternalHelpCab.

Other publishing options

Markdown is a versatile format that's easy to transform to other formats for publishing. Using a tool like Pandoc, you can convert your Markdown help files to many different document formats, including plain text, HTML, PDF, and Office document formats.

Also, the cmdlets ConvertFrom-Markdown and Show-Markdown in PowerShell 6 and higher can be used to convert Markdown to HTML or create a colorful display in the PowerShell console.

Known issues

PlatyPS is very sensitive to the schema for the structure of the Markdown files it creates and compiles. It's very easy write valid Markdown that violates this schema. For more information, see the PowerShell style guide and Editing reference articles.