PowerShell / platyPS

Write PowerShell External Help in Markdown
MIT License
765 stars 149 forks source link

[Markdown.MAML.Renderer.MamlRenderer].MamlModelToString loses links from the command:relatedLinks section #584

Open jhoneill opened 2 years ago

jhoneill commented 2 years ago

Prerequisites

Steps to reproduce

  1. As a test file I have download the MD help file for Get-Help from. https://github.com/MicrosoftDocs/PowerShell-Docs/blob/main/reference/7.2/Microsoft.PowerShell.Core/Get-Help.md
  2. In VS Code I have set a break point on new-externalHelp but the important part is the line $xml = $r.MamlModelToString($maml) (912 in the .PSM1 file for v 0.14.2 )
  3. After this line has run examine $maml.links and the last part $xml.
 $maml.links

IsSimplifiedTextLink LinkName                            LinkUri
-------------------- --------                            -------
               False Online Version:                     https://docs.microsoft.com/powershell/module/microsoft.powershell.core/get-help?view=powershell-7.2&WT.mc_id=ps-gethelp
               False about_Command_Syntax                About/about_Command_Syntax.md
               False about_Comment_Based_Help            ./About/about_Comment_Based_Help.md
               False Get-Command                         Get-Command.md
               False Supporting Updatable Help           /powershell/scripting/developer/module/supporting-updatable-help
               False Update-Help                         Update-Help.md
               False Writing Comment-Based Help Topics   /powershell/scripting/developer/help/writing-comment-based-help-topics
               False Writing Help for PowerShell Cmdlets /powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets

The first line is a fully qualified path. When the markdown is translated to HTML for on-line help the other links are translated to suitable paths (including removing the MD from names of other topics. However when it is translated here, the relative links are not processed, so the end of the xml looks like this

<command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version:</maml:linkText>
        <maml:uri>https://docs.microsoft.com/powershell/module/microsoft.powershell.core/get-help?view=powershell-7.2&amp;WT.mc_id=ps-gethelp</maml:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>about_Command_Syntax</maml:linkText>
        <maml:uri></maml:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>about_Comment_Based_Help</maml:linkText>
        <maml:uri></maml:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Get-Command</maml:linkText>
        <maml:uri></maml:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Supporting Updatable Help</maml:linkText>
        <maml:uri></maml:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Update-Help</maml:linkText>
        <maml:uri></maml:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Writing Comment-Based Help Topics</maml:linkText>
        <maml:uri></maml:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Writing Help for PowerShell Cmdlets</maml:linkText>
        <maml:uri></maml:uri>
      </maml:navigationLink>
    </command:relatedLinks>

Some links (about_ and other cmdlets) make sense. Others "Writing...." ones don't

Expected behavior

Get-Help Get-help has section which looks like 

RELATED LINKS
    Online Version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/get-help?view=powershell-7.2&WT.mc_id=ps-gethelp
...
    Writing Help for PowerShell Cmdlets https://docs.microsoft.com/en-us/powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets

Actual behavior

It looks like 
RELATED LINKS
    Online Version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/get-help?view=powershell-7.2&WT.mc_id=ps-gethelp
...
    Writing Help for PowerShell Cmdlets

Error details

No message

Environment data

Directory: C:\Program Files\WindowsPowerShell\Modules

ModuleType Version    PreRelease Name                                PSEdition ExportedCommands
---------- -------    ---------- ----                                --------- ----------------
Script     0.14.2                platyPS                             Desk      {New-MarkdownHelp, Get-MarkdownMetadata, New-ExternalHelp, New-YamlHelp}

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

Visuals

No response