Export-MamlCommandHelp does not convert lists from markdown help.

[peetrike]

Prerequisites

• Write a descriptive title.
• Make sure you are able to repro it on the latest version
• Search the existing issues.

Steps to reproduce

In the generated MAML help the lists in markdown documents are not preserved, instead all list elements are joined to one line.

Expected behavior

Lists in MAML help should be preserved. At least every list element in separate line/paragraph

Actual behavior

List elements are converted to single line.

Error details

Environment data

PowerShell 5.1 and 7.5.2

Version

1.0.0

Visuals

No response

[sdwheeler]

@peetrike Can you provide an example of the problem you are seeing?

[peetrike]

when there is list in the markdown, the generated MAML has all list elements in same line. for example:

• element
• another element

is converted to text in MAML:

- element - another element

but v0.14.2 version of module converted it to:

- element
- another element

Similar effect appears with bold text. The converted text in MAML is like:

Similar effect appears with **bold** text.

[sdwheeler]

Please provide an example command that has the list problem or provide steps to reproduce the problem. I am not finding an example.

As for the markdown markup (bold, code fences, etc.) that is by design.

[peetrike]

Simple example of the results can be achieved with script MamlConversion.ps1

The script generates simple module, saves Markdown help contents and MAML module help file. There are visible both abovementioned problems, in function description

[peetrike]

As for the markdown markup (bold, code fences, etc.) that is by design.

Is it documented somewhere? It makes reading the help contents harder. Or do you plan to change the rendering of help contents also?

[sdwheeler]

Copied example from your script file here for easier access.

$ModuleName = 'SayHello'
New-Module -Name $ModuleName -ScriptBlock {
    function get-hello {
        <#
            .SYNOPSIS
                Says hello
            .DESCRIPTION
                some examples for platyPS

                - regular text
                - text having **bold** in it
        #>
        'Hello'
    }
} | Import-Module

Get-Command -Module $ModuleName |
    New-CommandHelp |
    Export-MarkdownCommandHelp -OutputFolder $PSScriptRoot

Get-ChildItem -Path "$PSScriptRoot\$Modulename\*.md" |
    Import-MarkdownCommandHelp |
    Export-MamlCommandHelp -OutputFolder $PSScriptRoot

[sdwheeler]

Is it documented somewhere? It makes reading the help contents harder. Or do you plan to change the rendering of help contents also?

No changes planned. This is the new normal. We will investigate the flattening of the lists in the MAML. The list problem is not happening everywhere in the MAML so this may be isolated to the DESCRPTION section.

[teramako]

The generation of the DESCRIPTION section is special, with only one newline in the code to be concatenated. This may be the cause of the problem.

platyPS/src/MamlWriter/MamlHelpers.cs

Lines 67 to 73 in 7234f18

	if (commandHelp.Description is not null)
	{
	foreach(string s in commandHelp.Description.Split(new string[] { "\n\n" }, StringSplitOptions.None))
	{
	command.Description.Add(s.Replace("\n"," ").Trim());
	}
	}

Other codes, such as PARAMETER, do not do that.

platyPS/src/MamlWriter/MamlHelpers.cs

Lines 196 to 202 in 7234f18

	if (parameter.Description is not null)
	{
	foreach(string s in parameter.Description.Split(new string[] { "\n\n" }, StringSplitOptions.None))
	{
	newParameter.Description.Add(s.Trim());
	}
	}

[teramako]

No changes planned. This is the new normal. We will investigate the flattening of the lists in the MAML. The list problem is not happening everywhere in the MAML so this may be isolated to the DESCRPTION section.

I have found lists and block quotes in the DESCRIPTION section of the PowerShell documentation.

e.g.)

• https://github.com/MicrosoftDocs/PowerShell-Docs/blob/main/reference/7.4/Microsoft.PowerShell.Core/ForEach-Object.md
• https://github.com/MicrosoftDocs/PowerShell-Docs/blob/main/reference/7.4/Microsoft.PowerShell.Core/Enable-PSRemoting.md

At that now, these DESCRIPTIONs will not be readable text. I still think they need to be fixed.