Skip to main content
Version: v2

Multi-Line Examples

PowerShell's Comment Based Help was originally designed for .EXAMPLE nodes containing:

  • Only a single-line example
  • Followed by the command's output and/or a description
.EXAMPLE

  Get-RealName -NickName "SomeNick"

  Yasmine

Code Fence Detection​

Unfortunately these single-line examples no longer suffice as authors are now creating advanced functions which require complex multi-lined code examples to properly inform their end-users.

Because Microsoft does not (and cannot) support these use-cases, Docusaurus comes with Code Fence Detection, allowing you to use markdown code fences to indicate where your example code block starts and where it ends.

Code fencing ensures identical rendering across all PowerShell versions and looks similar to:

.EXAMPLE
    ```ps
    $description = 'Code Fenced example with a description'
    $names | Foreach-Object {} {
        Write-Host 'Indentation and empty newlines within the fenced code block will be respected'
    }

    $multipleNewlinesInCode = $True
    ```

    Your description would start here and:

    - is treated as markdown
    - could also contain fenced code blocks itself

Please note that you may use any of the following commonly used opening fences:

  • ```
  • ```ps
  • ```posh
  • ```powershell

For a full list of usage examples see this test module and the markdown it renders.

Native Multi-Lines​

PowerShell also ships with native support for multi-line code examples but it only supports a single use-case as can be seen in this example:

.EXAMPLE
    $exampleType = 'Native multi-line example with a description'
    $info = 'Get-Help will treat all adjacent lines as code'
    $info = 'The code block will end at the first double-newline`

    Get-Help will thus use this line, and everything below it, as the description

You could consider using native multi-lines instead of Code Fence Detection if your example code does not contain any blank lines.

Default Fallback​

If code fencing is not detected, Docusaurus.Powershell will treat the first paragraph of the example (all lines up to the first blank line) as code and everything below it as the description, exactly matching the native Get-Help behavior described above.

Unexpected Results​

If your example code is not being rendered as expected please make sure to understand why it is not being recognized as multi-line code before creating an issue or pull request. Most likely, updating your help to use Code Fence Detection would be the better alternative.

Additional Information​