Creates a markdown Readme document from the comment based help of a PowerShell command
Get-MarkdownHelp
-Path <Object>
[-Command <Object>]
[-PSCodePattern <String> = 'PS.*\>\s?']
[-AlternateEOL <String> = '\']
[<CommonParameters>]Get-MarkdownHelp
-ScriptBlock <Object>
[-Command <Object>]
[-PSCodePattern <String> = 'PS.*\>\s?']
[-AlternateEOL <String> = '\']
[<CommonParameters>]The Get-MarkdownHelp cmdlet retrieves the comment-based help and converts it to a Markdown page
similar to the general online PowerShell help pages (as e.g. Get-Content).
Note that this cmdlet doesn't support XML-based help files, but has a few extra features for the
comment-based help as opposed to the native platyPS New-MarkdownHelp:
To create code blocks, indent every line of the block by at least four spaces or one tab relative the
text indent.
The text indent is defined by the smallest indent of the current - and the .SYNOPSIS section.
Code blocks are automatically fenced for default PowerShell color coding.
The usual comment-based help prefix for code (PS. \>) might also be used to define a code lines.
For more details, see the -PSCodePattern parameter.
As defined by the standard help interpreter, code blocks (including fenced code blocks) can't include help
keywords. Meaning (fenced) code blocks will end at the next section defined by .<help keyword>.
Examples can be titled by adding an (extra) hash (#) in front of the first line in the section.
This line will be removed from the section and added to the header of the example.
As per markdown definition:
The first part of a reference-style link is formatted with two sets of brackets. The first set of brackets surrounds the text that should appear linked. The second set of brackets displays a label used to point to the link you're storing elsewhere in your document, e.g.:
[rabbit-hole][1]. The second part of a reference-style link is formatted with the following attributes:
- The label, in brackets, followed immediately by a colon and at least one space (e.g.,
[label]:).- The URL for the link, which you can optionally enclose in angle brackets.
- The optional title for the link, which you can enclose in double quotes, single quotes, or parentheses.
For the comment-base help implementation, the second part should be placed in the .LINK section to automatically
listed in the end of the document. The reference will be hidden if the label is an explicit empty string("").
Any phrase between squared brackets that starts with a word character, e.g. [my link], will be automatically
linked to the element where the id is defined by the enclosed phrase and converting the consecutive non-word
characters to a single hyphen (and removing any outer hyphens). In this example: [my link](#my-link)
Warning
There is no check whether the internal anchor id actually exists.
Example links are based on Quick Links but start with a the word "example" followed by the example index (possibly separated by a space) or the word "example" followed by the example caption. Where the caption is used to identify the link by converting its consecutive non-word characters to a single hyphen.
Examples:
[example 1]will link to the first (example 1) in this document[example 2 with any caption]will link to the second (example 2 -regardless the caption-) in this document[example "Save markdown help to file"]will link to the (example "Save markdown help to file") in this document
Parameter links are similar to Quick Links but start with a hyphen and contain an existing parameter
name possibly followed by the word "parameter". E.g.: [-AlternateEOL] or [-AlternateEOL parameter].
In this example, the parameter link will refer to the internal -AlternateEOL parameter.
Cmdlet links are similar to Quick Links but contain a cmdlet name where the online help is known. E.g.: [Get-Content].
In this example, the cmdlet link will refer to the online help of the related Get-Content cmdlet.
This example generates a markdown format help page from itself and shows it in the default browser
.\Get-MarkdownHelp.ps1 .\Show-MarkDown.ps1 | Out-String | Show-Markdown -UseBrowserThis command creates a markdown readme string for the Join-Object cmdlet and puts it on the clipboard
so that it might be pasted into e.g. a GitHub readme file.
Get-MarkdownHelp Join-Object | ClipThis command creates a markdown readme string for the .\MyScript.ps1 script and saves it in Readme.md.
Get-MarkdownHelp .\MyScript.ps1 | Set-Content .\Readme.mdAn embedded command that contains the parameters or actual commented help.
Name: -Path
Aliases: -Source
Type: [Object]
Value (default): # Undefined
Parameter sets: Path
Mandatory: True
Position: # Named
Accept pipeline input: False
Accept wildcard characters: FalseThe script content that contains the commented help.
Name: -ScriptBlock
Aliases: # None
Type: [Object]
Value (default): # Undefined
Parameter sets: Script
Mandatory: True
Position: # Named
Accept pipeline input: False
Accept wildcard characters: FalseA specific command or function contained by the script file of block.
Name: -Command
Aliases: # None
Type: [Object]
Value (default): # Undefined
Parameter sets: # All
Mandatory: False
Position: # Named
Accept pipeline input: False
Accept wildcard characters: FalseSpecifies the PowerShell code pattern used by the get-help cmdlet.
The native [Get-Help] cmdlet automatically adds a PowerShell prompt (PS \>) to the first line of an example if not yet exist.
To be consistent with the first line you might manually add a PowerShell prompt to each line of code which will be converted to
a code block by this Get-MarkdownHelp cmdlet.
Name: -PSCodePattern
Aliases: # None
Type: [String]
Value (default): 'PS.*\>\s?'
Parameter sets: # All
Mandatory: False
Position: # Named
Accept pipeline input: False
Accept wildcard characters: FalseThe recommended way to force a line break or new line (<br>) in markdown is to end a line with two or more spaces but as that
might cause an Avoid Trailing Whitespace warning, you might also consider to use an alternate EOL marker.
Any alternate EOL marker (at the end of the line) will be replaced by two spaces by this Get-MarkdownHelp cmdlet.
Name: -AlternateEOL
Aliases: # None
Type: [String]
Value (default): '\'
Parameter sets: # All
Mandatory: False
Position: # Named
Accept pipeline input: False
Accept wildcard characters: FalseA (reference to a) command or module
String[]