platyPS: Multiline examples don't display as markdown code

This particular issue as i understand it only applies one inital help import into markdown. So a copy/paste from help to markdown would also allow you to work around the issue.

@Greg-Smulko thank you kindly for confirming, always better to be 100% sure beforehand.

For other users that might be interested in this topic… the Pester documentation website required supporting more complex code examples (that contain double-newlines in the code itself). After trying various solutions, the one that won is Code Fence Detection, applied during PlatyPS post-processing.

It basically allows you to use common markdown code fences in your Get-Help examples. For more information see:

• this end-user usage guide
• these get-help usage examples and the correlating rendered markdown
• this step-by-step explanation of all required technical steps and regexes used to support this on Powershell 5, 6 and 7

ps this still respects your PS7 native multi-line support 🎉

Vendor Agnostic

We added support for vendor agnostic output so our module can now also be used by users who want to render code fenced get-help but do not want to use Docusaurus to serve their pages.

Marking as closed as it is no longer an issue due to the excellent work done by @Greg-Smulko based on @vors comments.

@bravo-kernel , yes, you’re correct. Everything up to the first double new line is treated as code, and then the rest is a description. The reasoning behind this is that a multi-paragraph description is quite common, and otherwise, it wouldn’t be possible to figure out where the code ends and description begins (without some heuristics or relying on a prompt PS>).

If you want to take a look at supported examples, please take a look at the tests added as part of the PR in the PowerShell repo.

To be more precise, the bug is here:

https://github.com/PowerShell/PowerShell/blob/bd6fdae73520931f0d27a29d6290e18761772141/src/System.Management.Automation/help/HelpCommentsParser.cs#L514,L521

We are cutting off the code_str at the first \n char. I think it’s reasonable to rewrite this hand-written state machine as a regex parsing. The logic in the file is generating xmls on the fly so the performance bottleneck is not going to be in one regex application.

Would you care to try to include such heuristic in platypus when we generate the examples code from Get-Help object?

I created a big of regex magic to fix this issue, it can help somebody hopefully.

    New-MarkdownHelp -Module MyModuleToDocument -OutputFolder $OutputDir -Force

    $OutputDir | Get-ChildItem -File | ForEach-Object {
        # fix formatting in multiline examples
        $content = Get-Content $_.FullName -Raw
        $newContent = $content -replace '(## EXAMPLE [^`]*)(```\r\n)([^`]*)(```\r\n)(\r\n)([^#]*)(\r\n\r\n)+([^#]+)(#)', '$1$2$3$6$5$4$7$8$9'
        if ($newContent -ne $content) {
            Set-Content -Path $_.FullName -Value $newContent -Force
        }
    }