PowerShell
Export-MamlCommandHelp does not convert lists from markdown help.
Prerequisites
- [x] Write a descriptive title.
- [x] Make sure you are able to repro it on the latest version
- [x] 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
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.
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.
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
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?
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
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.
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.
https://github.com/PowerShell/platyPS/blob/7234f18090d39fd24c1266d08f2d66965e71e565/src/MamlWriter/MamlHelpers.cs#L67-L73
Other codes, such as PARAMETER, do not do that.
https://github.com/PowerShell/platyPS/blob/7234f18090d39fd24c1266d08f2d66965e71e565/src/MamlWriter/MamlHelpers.cs#L196-L202
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.