New-YamlHelp

Reference

Module:: platyPS

Converts Markdown help into YAML to be read easily by external tools

Syntax

New-YamlHelp
   [-Path] <String[]>
   -OutputFolder <String>
   [-Encoding <Encoding>]
   [-Force]
   [<CommonParameters>]

Description

The New-YamlHelp cmdlet works similarly to the New-ExternalHelp cmdlet but rather than creating a MAML file to support Get-Help, it creates a set of YAML files that can be read by external tools to provide custom rendering of help pages.

Examples

Example 1: Create YAML files

PS C:\> New-YamlHelp -Path .\docs -OutputFolder .\out\yaml

    Directory: D:\Working\PlatyPS\out\yaml


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        6/15/2017  11:13 AM           2337 Get-HelpPreview.yml
-a----        6/15/2017  11:13 AM           3502 Get-MarkdownMetadata.yml
-a----        6/15/2017  11:13 AM           4143 New-ExternalHelp.yml
-a----        6/15/2017  11:13 AM           3082 New-ExternalHelpCab.yml
-a----        6/15/2017  11:13 AM           2581 New-MarkdownAboutHelp.yml
-a----        6/15/2017  11:13 AM          12356 New-MarkdownHelp.yml
-a----        6/15/2017  11:13 AM           1681 New-YamlHelp.yml
-a----        6/15/2017  11:13 AM           5053 Update-MarkdownHelp.yml
-a----        6/15/2017  11:13 AM           4661 Update-MarkdownHelpModule.yml
-a----        6/15/2017  11:13 AM           3350 Update-MarkdownHelpSchema.yml

This creates one YAML file for each cmdlet so external tools can read the structured data for each cmdlet.

Example 2: Create YAML files with specific encoding

PS C:\> New-YamlHelp -Path .\docs -OutputFolder .\out\yaml -Force -Encoding ([System.Text.Encoding]::Unicode)

    Directory: D:\Working\PlatyPS\out\yaml


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        6/15/2017  11:13 AM           2337 Get-HelpPreview.yml
-a----        6/15/2017  11:13 AM           3502 Get-MarkdownMetadata.yml
-a----        6/15/2017  11:13 AM           4143 New-ExternalHelp.yml
-a----        6/15/2017  11:13 AM           3082 New-ExternalHelpCab.yml
-a----        6/15/2017  11:13 AM           2581 New-MarkdownAboutHelp.yml
-a----        6/15/2017  11:13 AM          12356 New-MarkdownHelp.yml
-a----        6/15/2017  11:13 AM           1681 New-YamlHelp.yml
-a----        6/15/2017  11:13 AM           5053 Update-MarkdownHelp.yml
-a----        6/15/2017  11:13 AM           4661 Update-MarkdownHelpModule.yml
-a----        6/15/2017  11:13 AM           3350 Update-MarkdownHelpSchema.yml

This will both read and write the files in the specified -Encoding. The Force parameter will overwrite files that already exist.

Parameters

-Encoding

Specifies the character encoding for your external help file. Specify a System.Text.Encoding object. For more information, see about_Character_Encoding.

Type:	Encoding
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Force

Indicates that this cmdlet overwrites an existing file that has the same name.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-OutputFolder

Specifies the folder to create the YAML files in

Type:	String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Path

Specifies an array of paths of markdown files or folders. This cmdlet creates external help based on these files and folders.

Type:	String[]
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

Inputs

String[]

You can pipe an array of paths to this cmdlet.

Outputs

FileInfo[]

This cmdlet returns a FileInfo[] object for created files.