Get-MarkdownHelp

The [Get-MarkdownHelp][1] cmdlet retrieves the [comment-based help][2] 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][3] [New-MarkdownHelp]:

### Code Blocks

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][4] 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>`.

### Titled Examples

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.

### Links

As per markdown definition:
> The first part of a [reference-style link][5] 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(`""`).

### Quick Links

Any phrase between squared brackets, 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

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

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

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