Markdown Formatting Issues

[TrisBits]

Prerequisites

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

Steps to reproduce

Issue occurs if the comment-based help, does not include a .LINK section.

Comment-based Help to produce test scenarios.

Scenario 1 - .LINK present but left empty

function Test-Cmdlet {
    <#
    .SYNOPSIS
    Testing of comment-based help.

    .DESCRIPTION
    This is utilized to test Microsoft.PowerShell.PlatyPS.

    .PARAMETER Test
    A placehoder parameter for testing documentation output.

    .EXAMPLE
    Test-Cmdlet -Name "MyName"

    .EXAMPLE
    This is example text before the command.
    Test-Cmdlet -Name 'MyName'

    .INPUTS

    .OUTPUTS

    .NOTES

    .LINK
    #>

    param (
        [Parameter(Mandatory=$false, HelpMessage="A parameter for platyPS testing purposes.")]
        [string]$Name
    )

    Write-Host 'This is a test.'
}

Scenario 2 - .LINK not present

function Test-Cmdlet {
    <#
    .SYNOPSIS
    Testing of comment-based help.

    .DESCRIPTION
    This is utilized to test Microsoft.PowerShell.PlatyPS.

    .PARAMETER Test
    A placehoder parameter for testing documentation output.

    .EXAMPLE
    Test-Cmdlet -Name "MyName"

    .EXAMPLE
    This is example text before the command.
    Test-Cmdlet -Name 'MyName'

    .INPUTS

    .OUTPUTS

    .NOTES
    #>

    param (
        [Parameter(Mandatory=$false, HelpMessage="A parameter for platyPS testing purposes.")]
        [string]$Name
    )

    Write-Host 'This is a test.'
}

Scenario 3 - .NOTE has information

function Test-Cmdlet {
    <#
    .SYNOPSIS
    Testing of comment-based help.

    .DESCRIPTION
    This is utilized to test Microsoft.PowerShell.PlatyPS.

    .PARAMETER Test
    A placehoder parameter for testing documentation output.

    .EXAMPLE
    Test-Cmdlet -Name "MyName"

    .EXAMPLE
    This is the example text before the command.
    Test-Cmdlet -Name 'MyName'

    .INPUTS

    .OUTPUTS

    .NOTES
    This is a sample note.

    .LINK
    #>

    param (
        [Parameter(Mandatory=$false, HelpMessage="A parameter for platyPS testing purposes.")]
        [string]$Name
    )

    Write-Host 'This is a test.'
}

    $newMarkdownCommandHelpSplat = @{
        ModuleInfo = Get-Module MySample
        OutputFolder = '.'
        HelpVersion = '0.0.1'
        WithModulePage = $true
    }

    New-MarkdownCommandHelp @newMarkdownCommandHelpSplat

Expected behavior

Scenario 1 Expected:

Scenario 2 Expected:

Scenario 3 Expected:

Actual behavior

Scenario 1 Result - An empty bullet point is produced in RELATED LINKS

Scenario 2 Result - The RELATED LINKS placeholder is created as expected, but an extra space is added at end of file

Scenario 3 Result - When NOTES has a value, an extra space is added

Error details

Environment data

Name                           Value
----                           -----
PSVersion                      7.4.12
PSEdition                      Core
GitCommitId                    7.4.12
OS                             Microsoft Windows 10.0.26100
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Version

1.0.1

Visuals

No response

[TrisBits]

Conversely, if a .LINK is added but left empty the resulting Markdown adds an empty bullet point rather than a completely empty section.

RELATED LINKS

[TrisBits]

Since the yaml for Parameters is in a language specified code block. Should the __AllParameterSets code block be defined as text?

[sdwheeler]

Please provide examples of your comment-based help, the problematic output, and the expected output.

[TrisBits]

@sdwheeler Issue updated with requested details.

[TrisBits]

Since the yaml for Parameters is in a language specified code block. Should the __AllParameterSets code block be defined as text?

As for this comment, I was also wondering the following.

Should it instead be specified as something like powershell or even text, to make Markdown linters happy?

That would conform with what was already done for Parameters.

[sdwheeler]

__AllParameterSets is the name of the parameter set. This is by design. The code block is a representation of the syntax, not PowerShell code. There is no code fence label because there is no Markdown highlighter for BNF-style syntax. In the Parameters, the Yaml code block is Yaml formatted metadata about the parameter. In that case, the code fence label is appropriate.

[sdwheeler]

PowerShell parses the comment-based help and create help objects that PlatyPS uses.

Scenario 1 - .LINK present but left empty

This is expected behavior.

Get-Help Test-Cmdlet | select relatedLinks

relatedLinks
------------
@{navigationLink=@{linkText=}}

For the other two scenarios, the extra blank lines are a minor inconvenience. We will look into fix it, but it's low priority. Even if we fix it, you always need to edit the markdown produced by PlatyPS.