Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Markdown Formatting Issues

Open
  • Is something wrong?
#830 7 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
48/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Stale
Tech stack
powershell
Domain
documentation

Research direction

Start by reproducing the three scenarios with New-MarkdownCommandHelp using the comment-based help examples in the issue, then inspect the generated Markdown for RELATED LINKS and trailing spaces. Done means an empty .LINK does not create an empty bullet, the missing .LINK case has the expected placeholder without extra trailing space, and populated .NOTES adds no extra space.

Written by the indexing model from the issue text.

Description

Area-Comment-Based-Help
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:

Image

Scenario 2 Expected:

Image

Scenario 3 Expected:

Image
Actual behavior

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

Image

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

Image

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

Image
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

Dominant language
C#
Stars
870
Forks
166
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from PowerShell/platyPS

All issues in PowerShell/platyPS

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.