Valid markdown line ends are causing markdown -> maml convertion error

[fourpastmidnight]

Steps to reproduce

In Markdown, just pressing Enter doesn't necessarily mean that a line-break will be rendered in the document when it's transformed to HTML. So markdown originally specified that you could append two trailing spaces to the end of the line to signify that the line should be followed by a <br /> when rendered to HTML. GitHub flavored Markdown (GFM) allows you to simply append a \ to the end of the line to achieve the same thing. For example:

[about\_My.Module](about_My.Module.md)__ <!-- Here, the two underscores represent spaces -->
[Get-MyFunction](Get-MyFunction.md)
<!-- OR -->
[about\_My.Module](about_My.Module.md)\
[Get-MyFunction](Get-MyFunction.md)

Expected behavior

I expected that even if GFM isn't supported, that at least appending two trailing spaces would've been supported so that the following HTML would be generated:

<a href="about_My.Module.md">about_My.Module</a><br />
<a href="Get-MyFunction.md">Get-MyFunction</a>

Actual behavior

Both of the examples above fail with platyPS due to the extra spaces or the \. But if I don't use either of the methods which force a line-break, then the rendered HTML results in the links all showing up one after another on a single line by some markdown parsers, such as the one used by Atlassian Stash/BitBucket:

<a href="about_My.Module.md">about_My.Module</a><a href="Get-MyFunction.md">Get-MyFunction</a>

Environment data

PowerShell v5.1 platyPs 0.11.1

[vors]

We indeed trying to complay to https://spec.commonmark.org/0.28/#hard-line-break for generated markdown. But I could not figure out where is platyPS comes into play? The issue you described sounds like one that is dealing with the markdown -> html convertion. PlatyPS doesn't generate html, it converts between powershell help (MAML) and markdown.

Perhaps you are talking about markdown -> maml ?

[fourpastmidnight]

Where platyPS comes into play is that it does not accept trailing spaces nor a backslash after any related link markdown. platyPS emits an error when generating the MAML.

[vors]

Oh I see, that's pretty bad indeed.

[fourpastmidnight]

Well, I'm happy to report that other than this issue I ran into, so far, I've been able to generate the PS help documentation for my module. Thanks for the hard work on this project.

[vors]

yay, great to hear!

Switching to a proper markdown parser would be an ultimate fix for that issue. But this a pretty big task. #112

[fourpastmidnight]

One workaround for this issue is to separate the lines with an additional newline in between. This forces each link into its own separate paragraph and renders correctly in BitBucket (which, IMO has not so great markdown rendering (well, at least BitBucket Server 4.14--yeah, I'm behind on that!)

[sdwheeler]

This will probably be fixed when we switch to the markdig engine.

[sdwheeler]

Microsoft.PowerShell.PlatyPS v1 uses markdig.