< Back

New-YamlHelp

Sat Jan 18, 2020 7:08 pm

NAME New-YamlHelp



SYNOPSIS

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





SYNTAX

New-YamlHelp [-Path] <String[]> [-Encoding <Encoding>] [-Force] -OutputFolder <String> [<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.





PARAMETERS

-Encoding <Encoding>

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

information, see Character Encoding in the .NET Framework

(https://msdn.microsoft.com/en-us/library/ms404377.aspx)in the Microsoft Developer Network. For example, you

can control Byte Order Mark (BOM) preferences. For more information, see Using PowerShell to write a file in

UTF-8 without the BOM

(http://stackoverflow.com/questions/5596 ... ut-the-bom)at the

Stack Overflow community.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-Force [<SwitchParameter>]

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



Required? false

Position? named

Default value False

Accept pipeline input? False

Accept wildcard characters? false



-Path <String[]>

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

files and folders.



Required? true

Position? 1

Default value None

Accept pipeline input? True (ByPropertyName, ByValue)

Accept wildcard characters? false



-OutputFolder <String>

Specifies the folder to create the YAML files in



Required? true

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



<CommonParameters>

This cmdlet supports the common parameters: Verbose, Debug,

ErrorAction, ErrorVariable, WarningAction, WarningVariable,

OutBuffer, PipelineVariable, and OutVariable. For more information, see

about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).



INPUTS

System.String[]

You can pipe an array of paths to this cmdlet.





OUTPUTS

System.IO.FileInfo[]

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





NOTES









----------------- 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.



RELATED LINKS

Online Version: https://github.com/PowerShell/platyPS/b ... amlHelp.md