< Back
New-YamlHelp
Post
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
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