Edit

Share via

New-MarkdownHelp

Module:
platyPS Module

Creates help in markdown format.

Syntax

FromModule 

New-MarkdownHelp
    -Module <String[]>
    -OutputFolder <String>
    [-Session <PSSession>]
    [-Force]
    [-AlphabeticParamsOrder]
    [-Metadata <Hashtable>]
    [-NoMetadata]
    [-UseFullTypeName]
    [-Encoding <Encoding>]
    [-WithModulePage]
    [-ModulePagePath <String>]
    [-Locale <String>]
    [-HelpVersion <String>]
    [-FwLink <String>]
    [-ExcludeDontShow]
    [<CommonParameters>]

FromCommand 

New-MarkdownHelp
    -Command <String[]>
    -OutputFolder <String>
    [-Session <PSSession>]
    [-Force]
    [-AlphabeticParamsOrder]
    [-Metadata <Hashtable>]
    [-OnlineVersionUrl <String>]
    [-NoMetadata]
    [-UseFullTypeName]
    [-Encoding <Encoding>]
    [-ExcludeDontShow]
    [<CommonParameters>]

FromMaml 

New-MarkdownHelp
    -MamlFile <String[]>
    -OutputFolder <String>
    [-ConvertNotesToList]
    [-ConvertDoubleDashLists]
    [-Force]
    [-AlphabeticParamsOrder]
    [-Metadata <Hashtable>]
    [-NoMetadata]
    [-UseFullTypeName]
    [-Encoding <Encoding>]
    [-WithModulePage]
    [-ModulePagePath <String>]
    [-Locale <String>]
    [-HelpVersion <String>]
    [-FwLink <String>]
    [-ModuleName <String>]
    [-ModuleGuid <String>]
    [-ExcludeDontShow]
    [<CommonParameters>]

Description

The New-MarkdownHelp cmdlet creates help in markdown format based on a module, a command, or a file in Microsoft Assistance Markup Language (MAML) format.

Examples

Example 1: Create help from a command

PS C:\> function Command03 {param([string]$Value)}
PS C:\> New-MarkdownHelp -Command "Command03" -OutputFolder ".\docs"


    Directory: D:\Working\docs


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        5/22/2016   6:53 PM            664 Command03.md

The first command creates a function named Command03 using standard Windows PowerShell syntax.

The second command creates help for that stub function in the .\docs folder.

Example 2: Create help from a module

PS C:\> Import-Module -Module "PlatyPS"
PS C:\> New-MarkdownHelp -Module "PlatyPS" -OutputFolder ".\docs" -Force


    Directory: D:\Working\PlatyPS\docs


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        5/22/2016   6:54 PM           1496 Get-HelpPreview.md
-a----        5/22/2016   6:54 PM           3208 Get-MarkdownMetadata.md
-a----        5/22/2016   6:54 PM           3059 New-ExternalHelp.md
-a----        5/22/2016   6:54 PM           2702 New-ExternalHelpCab.md
-a----        5/22/2016   6:54 PM           6234 New-MarkdownHelp.md
-a----        5/22/2016   6:54 PM           2346 Update-MarkdownHelp.md
-a----        5/22/2016   6:54 PM           1633 Update-MarkdownHelpModule.md
-a----        5/22/2016   6:54 PM           1630 Update-MarkdownHelpSchema.md

The first command loads the PlatyPS module into the current session using the Import-Module cmdlet.

The second command creates help for all the cmdlets in the PlatyPS module. It stores them in the .\docs folder. This command specifies the Force parameter. Therefore, it overwrites existing help markdown files that have the same name.

Example 3: Create help from an existing MAML file

PS C:\> New-MarkdownHelp -OutputFolder "D:\PSReadLine\docs" -MamlFile 'C:\Program Files\WindowsPowerShell\Modules\PSReadLine\1.1\en-US\Microsoft.PowerShell.PSReadLine.dll-help.xml'

    Directory: D:\PSReadLine\docs


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        5/22/2016   6:56 PM           7443 Get-PSReadLineKeyHandler.md
-a----        5/22/2016   6:56 PM           3586 Get-PSReadLineOption.md
-a----        5/22/2016   6:56 PM           1549 Remove-PSReadLineKeyHandler.md
-a----        5/22/2016   6:56 PM           5947 Set-PSReadLineKeyHandler.md
-a----        5/22/2016   6:56 PM          15320 Set-PSReadLineOption.md

This command creates help in markdown format for the specified help MAML file. You don't have to load the module, as in the previous example. If the module is already loaded, this command creates help based on the MAML file, not on the currently installed module.

Example 4: Create help from an existing MAML file for use in a CAB file

PS C:\> New-MarkdownHelp -OutputFolder "D:\PSReadLine\docs" -MamlFile 'C:\Program Files\WindowsPowerShell\Modules\PSReadLine\1.1\en-US\Microsoft.PowerShell.PSReadLine.dll-help.xml' -WithModulePage  -Force -ModuleName "PSReadLine"


    Directory: D:\PSReadLine\docs


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        5/22/2016   6:59 PM           7443 Get-PSReadLineKeyHandler.md
-a----        5/22/2016   6:59 PM           3586 Get-PSReadLineOption.md
-a----        5/22/2016   6:59 PM           1549 Remove-PSReadLineKeyHandler.md
-a----        5/22/2016   6:59 PM           5947 Set-PSReadLineKeyHandler.md
-a----        5/22/2016   6:59 PM          15320 Set-PSReadLineOption.md
-a----        5/22/2016   6:59 PM            942 PSReadLine.md

This command creates help in markdown format for the specified help MAML file, as in the previous example. This command also specifies the WithModulePage parameter and the ModuleName parameter. The command creates a file named PSReadLine.md that contains links to the other markdown files in this module and metadata that can be used to create .cab files.

Parameters

-AlphabeticParamsOrder

Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last. These parameters are common and hence have well-defined behavior.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Command

Specifies the name of a command in your current session. This can be any command supported by PowerShell help, such as a cmdlet or a function.

Parameter properties

Type:

String[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromCommand
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ConvertDoubleDashLists

Indicates that this cmdlet converts double-hyphen list bullets into single-hyphen bullets. Double-hyphen lists are common in Windows PowerShell documentation. Markdown accepts single-hyphens for lists.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromMaml
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ConvertNotesToList

Indicates that this cmdlet formats multiple paragraph items in the NOTES section as single list items.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromMaml
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Encoding

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

Parameter properties

Type:Encoding
Default value:UTF8 without BOM
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ExcludeDontShow

Exclude the parameters marked with DontShow in the parameter attribute from the help content.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Force

Indicates that this cmdlet overwrites existing files that have the same names.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-FwLink

Specifies the forward link for the module page. This value is required for .cab file creation. This value is used as markdown header metadata in the module page.

Type:String
Default value:None
Supports wildcards:False
DontShow:False
FromModule
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
FromMaml
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HelpVersion

Specifies the version of your help. This value is required for .cab file creation. This value is used as markdown header metadata in the module page.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromModule
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
FromMaml
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Locale

Specifies the locale of your help. This value is required for .cab file creation. This value is used as markdown header metadata in the module page.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromModule
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
FromMaml
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-MamlFile

Specifies an array of paths path of MAML .xml help files.

Parameter properties

Type:

String[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromMaml
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Metadata

Specifies metadata that this cmdlet includes in the help markdown files as a hash table of string-to-sting key-value pairs. This cmdlet writes the metadata in the header of each markdown help file.

The New-ExternalHelp cmdlet doesn't use this metadata. External tools can use this metadata.

Parameter properties

Type:Hashtable
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Module

Specifies an array of names of modules for which this cmdlet creates help in markdown format.

Parameter properties

Type:

String[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromModule
Position:Named
Mandatory:True
Value from pipeline:True
Value from pipeline by property name:False
Value from remaining arguments:False

-ModuleGuid

Specifies the GUID of the module of your help. This value is required for .cab file creation. This value is used as markdown header metadata in the module page.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromMaml
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ModuleName

Specifies the name of the module of your help. This value is required for .cab file creation. This value is used as markdown header metadata in the module page.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromMaml
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ModulePagePath

When WithModule parameter is used by default it puts .md file in same location as all other docs. With this parameter you can specify new name/location providing better placement options.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromModule
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
FromMaml
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-NoMetadata

Indicates that this cmdlet doesn't write any metadata in the generated markdown.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-OnlineVersionUrl

Specifies the address where the updatable help function downloads updated help. If you don't specify a value, the cmdlet uses an empty string.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromCommand
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-OutputFolder

Specifies the path of the folder where this cmdlet creates the markdown help files.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Session

Provides support for remote commands. Pass the session that you used to create the commands with Import-PSSession. This is required to get accurate parameters metadata from the remote session.

Parameter properties

Type:PSSession
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromModule
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
FromCommand
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-UseFullTypeName

Indicates that the target document will use a full type name instead of a short name for parameters.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-WithModulePage

Indicates that this cmdlet creates a module page in the output folder. This file has the name that the ModuleName parameter specifies. If you didn't specify that parameter, the cmdlet supplies the default name MamlModule. You can overwrite this setting using ModulePagePath which allows you to define different path for module page

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

FromModule
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
FromMaml
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

String

You can pipe module names to this cmdlet. These are the modules from which this cmdlet creates help markdown.

Outputs

FileInfo

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