platyPS: write External Help files in Markdown

Today we are glad to release a Preview of platyPS.

platyPS is a PowerShell module that converts PowerShell help files written as Markdown to other formats starting with MAML XML.

What’s the problem

Traditionally PowerShell external help files have been authored as MAML XML.MAML is cumbersome to edit by hand, and traditional tools and editors don’t support it for complex scenarios like they do with Markdown. And while comment-based help is nice for writing scripts and functions, especially where the source is available, for more complex scenarios (e.g. very large and/or C#/binary modules), it can be desirable to have documentation abstracted away from the codebase.

For example, in the future, we would like to have our cmdlet documentation easily accessible from the PowerShell-Docs repo,so that we can update it more easily and frequently. Furthermore, public documentation means that you, our community, can more easily contribute to any low-hanging fruit you see in our documentation as well.Lastly, we can track Issues and in progress work on this documentation from a single, public location.

Markdown

Markdown is widely adopted by the Open-Source community to author documentation.For example, the PowerShell team uses Markdown for DSC documentation.

Markdown was designed to be human-readable without rendering which makes it easy to write and edit. Many editors support it (Visual Studio Code, Sublime Text, and others), and many tools and collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely.

platyPS markdown schema

Unfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a particular way.We have defined a schema to determine how parameters are described, where scripts examples are shown and, so on.

Any authoring must not break this formatting or the MAML will not be generated correctly.The schema closely resembles the existing output format of Get-Help.

Legend

• {string} – single-line string value
• {{text}} – multi-line text
• // – line comment in schema
• tabs show the scopes of // for statements; they should not be included in the Markdown output.

Version 1.0.0

// for every command:
    # {Command name}

    ## SYNOPSIS
    {{Synopsis text}}

    ## DESCRIPTION
    {{Description text}}

    ## PARAMETERS

    // for every parameter
        // type and default value are non-mandatory
        ### {Parameter name} [{Parameter type}] = {Parameter default value}

        // parameter metadata
        ```powershell
        {{Parameter attributes as specified in param() block in PowerShell functions
        i.e. [Parameter(ParameterSetName = 'ByName')]
        }}
        ```

        {{Parameter description text}}

    ## INPUTS
    // for every input type
        #### {Input type}
        {{Description text}}

    ## OUTPUTS
    // for every output type
        ### {Output type}
        {{Description text}}

    ## EXAMPLES
    // for every example
        ### {Example Name}

        ```powershell
        {{Example body}}
        ```
        {{Example text explanation}}

    ## RELATED LINKS

    // for every link
        [{link name}]({link url})

You can find the current schema on GitHub.

What preview means

The tool and schema is by no means perfect, but it is fully functional and being used by the PowerShell team.Our intention with this release is to gain feedback quickly and adjust accordingly.

Known issues

• Only English language supported.
• Not all Markdown syntax is supported (e.g. tables)

How to use it?

You can install platyPS as module from the PowerShell Gallery:

Install-Module platyPS

Example 1

Create an initial Markdown template from command and copy it to clipboard:

Get-platyPSMarkdown -Command Get-MyCommandName | Set-Clipboard

Copy it to some MyModule.md file on disk.

Example 2

Make external help generation a part of your build process for the module.For example, here is how platyPS builds its own documentation:

# Generate help for the module
Import-Module $pwd\out\platyPS
$maml = Get-platyPSExternalHelp -Markdown (cat -Raw .\src\platyPS\platyPS.md)
mkdir out\platyPS\en-US -ErrorAction SilentlyContinue > $null
Set-Content -Path out\platyPS\en-US\platyPS.psm1-Help.xml -Value $maml -Encoding UTF8

Example 3

Preview Get-Help output for generated maml:

$generatedModule = New-PlatyPSModuleFromMaml -MamlFilePath $outMamlFilePath
$generatedModule.Cmdlets | % { Get-Help -Name "$($generatedModule.Name)\$_" -Full | Out-String }

Sergei Vorobev

PowerShell Team