In this issue:

• What's New as Markdown
• Markdown Revisions
  • Using a List
  • Headings
  • User References
  • Pull Requests
• Online Documentation
• Adding Metadata
• Convert-WhatsNew
• Summary

I know I have mentioned this before, but you can install a module from Microsoft and view information about what's new in PowerShell releases. The module contains a single command.

PS C:\> Get-Command Get-WhatsNew | Select Name,Version,Source

Name         Version Source
----         ------- ------
Get-WhatsNew 0.5.5   Microsoft.PowerShell.WhatsNew

If you don't have this, you will need to install the module first.

Install-PSResource Microsoft.PowerShell.WhatsNew

What's New as Markdown

Running the command will display a list of recent changes to PowerShell.

The command defaults to the latest stable release of PowerShell 7, although you can specify other versions.

The output is a Markdown document. You could easily send the output to a file and view it in your favorite Markdown viewer. Or you can use the PowerShell 7 Markdown cmdlets and view it directly in the console. However, be careful. You will be tempted to run a command like this:

Get-WhatsNew | Show-Markdown

But that will fail. This is why I stress the importance of reading the help.

PS C:\> Help Show-Markdown -Parameter InputObject

-InputObject <system.management.automation.psobject>
    A Markdown string that will be shown in the terminal. If you do not pass in a supported format, `Show-Markdown` will emit an error.

    Required?                    true
    Position?                    named
    Default value                None
    Accept pipeline input?       True (ByValue)
    Aliases                      none
    Accept wildcard characters?  falsebdi

The command is expecting single Markdown string. Get-WhatsNew is writing Markdown strings to the pipeline, but multiple strings.

PS C:\> Get-WhatsNew | Measure-Object | Select Count

Count
-----
  102

So the command will fail. The fix is to join the strings into a single string. But you don't need to write complicated code to use the -Join operator. You can use the Out-String cmdlet.

Get-WhatsNew | Out-String | Show-Markdown

Knowing how to troubleshoot is an important skill, even for something as simple as this. But let's get back to the output.

Markdown Revisions

I can tell that the document is referencing GitHub pull requests such as #20942.

- Fix -OlderThan and -NewerThan parameters for Test-Path when using PathType and date range (#20942][20942]) (Thanks @ArmaanMcleod!)

In an Markdown viewer, such as your browser it might me nice if those links were clickable to make it easier to learn more. The same is true of the user reference, e.g.e @ArmaanMcleod. You can probably guess that I'll need to use regular expressions.

I would also like to improve the headings and use proper casing. Instead of this:

## Experimental features

I want it to be:

## Experimental Features

It is a little thing, but it makes a difference in the overall appearance of the document and adds a touch of professionalism.

For today, I want to step through the process of enhancing the Markdown output. I am processing a Markdown document, but you could use the same techniques for any text document that you want to enhance or manipulate.

Using a List

Obviously, I am going to need to parse a lot of text. Instead of trying to manipulate all the text at once, I am going to read the document into a generic list of strings. I will be creating a function that will accept pipeline input, since I already know that Get-WhatsNew writes a series of strings to the pipeline. I'll initialize the generic list in the Begin block.

$doc = [System.Collections.Generic.List[string]]::New()

Each line in the document will be an item in the list. This makes it easier to process each line individually. However, now I have a design decision to make. Do I want to revise each line as necessary as I read it in the Process block? Or do I want to read the entire document first, and then process it in the End block? Or maybe a bit of both.