joshooaj / platyps

Write PowerShell External Help in Markdown

joshooaj.PlatyPS

Introduction

This repo is a fork of the official PlatyPS repo where I have updated the module to suit my needs. Once PlatyPS v1 is released with support for PowerShell 7.4 and a whole bunch of other improvements, I will be abandoning this repo in favor of the new and improved PlatyPS.

Differences

• Bumped target framework to netstandard2.0 and dropped net451 as a target. This may impact compatibility with other libraries your project(s) use, and limits .NET Framework compatibility to a minimum version of 4.6.1. See the .NET Standard version matrix.
• Added ProgressAction to the list of common parameters which eliminates the common parameter from being listed independently as a parameter in the markdown files produced by New-MarkdownHelp.
• Renamed module to joshooaj.platyPS and updated the module GUID to ensure there is no confusion that this is an independently published version of PlatyPS.
• Removed Windows-only tests from the Pester tests and updated tests as needed.
• Uses GitHub Actions to automate tests and publishing.
• Uses Nerdbank.GitVersioning to set the version number

(Mostly) Original README

PlatyPS provides a way to:

• Write PowerShell External Help in Markdown
• Generate markdown help (example) for your existing modules
• Keep markdown help up-to-date with your code

Markdown help docs can be generated from old external help files (also known as MAML-xml help), the command objects (reflection), or both.

PlatyPS can also generate cab files for Update-Help.

Why?

Traditionally PowerShell external help files have been authored by hand or using complex tool chains and rendered as MAML XML for use as console help. MAML is cumbersome to edit by hand, and common tools and editors don't support it for complex scenarios like they do with Markdown. PlatyPS is provided as a solution for allow documenting PowerShell help in any editor or tool that supports Markdown.

An additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios (e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have documentation abstracted away from the codebase. PlatyPS does not need source access to generate documentation.

Markdown is designed to be human-readable, without rendering. This makes writing and editing easy and efficient. Many editors support it (Visual Studio Code, Sublime Text, etc), and many tools and collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely.

Common setups

There are 2 common setups that are used:

1. Use markdown as the source of truth and remove other types of help.
2. Keep comment based help as the source of truth and periodically generate markdown for web-site publishing.

They both have advantages and use-cases, you should decide what's right for you. There is slight preference toward number 1 (markdown as the source).

Quick start

• Install joshooaj.platyPS module from the PowerShell Gallery:

Install-Module -Name joshooaj.platyPS -Scope CurrentUser
Import-Module joshooaj.platyPS

• Create initial Markdown help for MyAwesomeModule module:

# you should have module imported in the session
Import-Module MyAwesomeModule
New-MarkdownHelp -Module MyAwesomeModule -OutputFolder .\docs

• Edit markdown files in .\docs folder and populate {{ ... }} placeholders with missed help content.

• Create external help from markdown help

New-ExternalHelp .\docs -OutputPath en-US\

• Congratulations, your help is now in markdown!

• Now, if your module code changes, you can easily update your markdown help with

# re-import your module with latest changes
Import-Module MyAwesomeModule -Force
Update-MarkdownHelp .\docs

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.

The schema closely resembles the existing output format of the Get-Help cmdlet in PowerShell.

If you break the schema in your markdown, you will get error messages from New-ExternalHelp and Update-MarkdownHelp. You would not be able to generate extrenal help or update your markdown.

It may be fine for some scenarios, i.e. you want to have online-only version of markdown.

Usage

Supported scenarios:

• Create Markdown

  • Using existing external help files (MAML schema, XML).
  • Using reflection
  • Using reflection and existing internal external help files.
  • For a single cmdlet
  • For an entire module

• Update existing Markdown through reflection.

• Create a module page .md with summary. It will also allow you to create updatable help cab.

• Retrieve markdown metadata from markdown file.

• Create external help xml files (MAML) from platyPS Markdown.

• Create external help file cab

• Preview help from generated maml file.

Remoting

PlatyPS supports working with Import-PSSession aka implicit remoting. Just pass -Session $Session parameter to the platyPS cmdlets and it will do the rest.

Build

For information about building from sources and contributing see contributing guidelines.