Document Tricks with Pandoc and PowerShell

Today's content is a little different. I'm not going to focus on a specific PowerShell topic, but rather something I think of as "PowerShell adjacent." You have probably written Markdown documents for your PowerShell projects, such as modules. You most likely have a README file in your repository. Hopefully, you are using the PlatyPS module to create documentation. This too will generate Markdown files. Or maybe you simply like writing in Markdown.

Since you've created this content once, you might want to re-purpose it into different formats. Maybe you want a set of HTML documents you can post to a documentation website. Or maybe you need a set of PDF files? What about a Word document?

Fortunately, there is a single tool you can use for all of these tasks. And because it is a command-line tool, that means you can incorporate it into PowerShell and automate the process. I want to give you a brief introduction to Pandoc and demonstrate how it can be used with PowerShell.

Installing Pandoc

To get started, you will need the latest version of Pandoc installed on your desktop. You can find installation instructions here. You could also install it from GitHub.

I'll install using Winget.

winget install --id JohnMacFarlane.Pandoc

The installation will update your PATH environment variable so you can run Pandoc from any command prompt. However, you will need to restart your PowerShell session to pick up the change.

PS C:\> $env:path -split ";" | where {$_ -Match "pandoc"}
C:\Users\Jeff\AppData\Local\Pandoc\
PS C:\> $env:path -split ";" | where {$_ -Match "pandoc"} | Set-Location
PS C:\Users\Jeff\AppData\Local\Pandoc> dir

    Directory: C:\Users\Jeff\AppData\Local\Pandoc

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           7/28/2024  9:41 PM          20519 COPYING.rtf
-a---           7/28/2024  9:20 PM           8489 COPYRIGHT.txt
-a---           7/28/2024  9:41 PM         390601 Pandoc User's Guide.html
-a---           7/28/2024  9:41 PM      216364032 pandoc.exe

Getting Help

I'll guide you through some Pandoc basics, but you should take a quick look at the HTML user guide.

PS C:\Users\Jeff\AppData\Local\Pandoc> Invoke-Item '.\Pandoc User''s Guide.html'

You can also get help from the command line.

 pandoc --help

The help is extensive, but you can narrow it down using Select-String.

PS C:\> pandoc --help | Select-String list

                        --list-tables[=true|false]
                        --listings[=true|false]
                        --list-input-formats
                        --list-output-formats
                        --list-extensions[=FORMAT]
                        --list-highlight-languages
                        --list-highlight-styles

The basic syntax for Pandoc is pandoc --output . The input file can be a single Markdown file or a collection of files. The output file can be a single file or a directory. Pandoc will convert the input file(s) to the desired format.

Creating Fragments

You will probably always want to specify the output file. Here is a sample markdown file.

    # Sample Document

    This is a sample markdown document.

    ## Section 1

    I'll put first-level content here.

    ```powershell
    Get-CimInstance Win32_OperatingSystem |
    Select-Object RegisteredUser,InstallDate,
    @{Name="OS";Expression = {$_.Caption}},
    @{Name="Computername";Expression={$_.CSName}}
    ```

    ### Subsection 1

    Here is a subsection.

    ## Summary

    You can find me online [here](https://jdhitsolutions.github.io).

I want to convert this to an HTML fragment.