PowerShell / PowerShell/platyPS

Export-MarkdownCommandHelp renders .LINK entries as unusable markdown links

Open
#858 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C#
Stars
871
Forks
166
Avg merge
21h 17m
Merged PRs (30d)
1

Description

Prerequisites
  • Write a descriptive title.
  • Make sure you are able to repro it on the latest version
  • Search the existing issues.
Steps to reproduce
@'
function Test-Links {
    <#
        .SYNOPSIS
            A synopsis.
        .DESCRIPTION
            A description.
        .LINK
            https://example.com/docs
        .LINK
            about_CommonParameters
    #>
    [CmdletBinding()] param()
}
'@ | Set-Content Links.psm1

Import-Module ./Links.psm1
New-CommandHelp -CommandInfo (Get-Command Test-Links) |
    Export-MarkdownCommandHelp -OutputFolder . -Force
Expected behavior
## RELATED LINKS

- [https://example.com/docs](https://example.com/docs)
- about_CommonParameters


Bare URLs use the URI as the link text (the platyPS 0.14 behavior); text-only entries render as plain list items.
Actual behavior
## RELATED LINKS

- [](https://example.com/docs)
- [about_CommonParameters]()


Bare URLs produce a link without clickable text (invisible on most sites); text-only entries produce a link without a target.
Error details
No error thrown.

Suggested fix: use the URI as the link text when no text is available, and render text-only entries as plain list items instead of empty-target links.
Environment data
- Microsoft.PowerShell.PlatyPS 1.0.2
- PowerShell 7.5.8
Version

1.0.2

Visuals

No response

Additionally

Found while migrating Alt3.Docusaurus.Powershell to the v2 pipeline; downstream tracking: https://github.com/alt3/Docusaurus.Powershell/issues/248

Contributor guide

Open the contributing guide

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.

Research direction

Start by reproducing the issue with Export-MarkdownCommandHelp using the PowerShell script and .LINK entries shown above. Trace how the command formats bare URLs and text-only entries, then verify that URLs use their URI as link text and text-only entries render as plain list items without empty targets.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, powershell
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.