Converting PowerShell to Markdown

I have been working a lot with markdown documents over the last year or so, primarily due to all the books I've been working on published at Leanpub.com. With the growing use of markdown in projects like Platyps for generating help files and documentation, you will most likely be using markdown at some point. With that in mind, I decided to write a PowerShell function that would take pipeline output and convert it to a simple markdown document, following the same model as ConvertTo-HTML.

Learning markdown basics takes about 10 minutes. And even then, you don’t have to know anything about markdown to use my function. ConvertTo-Markdown is designed to take pipelined input and convert it to a code-fenced section of a markdown document. If you don’t know what this means, don’t worry about it. The function assumes you will want to include a top-level title. Although, this isn’t required if you are building a document with markdown fragments. I’ll show you an example later.

You’ll need to grab a copy of the function from GitHub.

https://gist.github.com/jdhitsolutions/c92fab5b7077799e4ba5da920f0679f0

Once loaded in your session, you can pipe a command to the convert function.

Like ConvertTo-HTML this doesn’t create a file. It only converts to markdown. Pipe the command to Out-File or Set-Content.

The function also lets you add markdown to display before and after the converted pipeline output.

get-service win* | 
ConvertTo-Markdown -Title "Win* Services" -PreContent "## $env:computername" -PostContent "_$(Get-Date)_" | 
Out-File c:\work\winsvc.md

Here’s the end result:

Where I think this will come in handy is when you want to create documentation. Here is a proof of concept script.

#SystemMarkdownReport.ps1

param(
[string]$Title = "System Configuration Report",
[string]$Computername = $env:COMPUTERNAME,
[ValidatePattern('\.md$')]
[string]$Filepath = "SystemReport.md"
)

. C:\scripts\Convertto-Markdown.ps1

$PSDefaultParameterValues.add("Get-Ciminstance:computername",$computername)

$pre = @"

This is a system configuration report for $($computername.toupper())
"@

$fragments = @()

$fragments+= ConvertTo-Markdown -Title $title -PreContent $pre

#Computersystem
$prop = 'Manufacturer','Model','SystemFamily','SystemSKUNumber','SystemType','NumberOfLogicalProcessors','NumberofProcessors','TotalPhysicalMemory' 
$cs = Get-CimInstance Win32_Computersystem -ov c -Property $prop | Select-Object -Property $prop 

$class = ($c.cimclass.cimclassname.split("_")[1])
$fragments+= $cs | ConvertTo-Markdown -precontent "## $class"

#volumes
$vol = Get-CimInstance win32_volume -ov c| Select-Object Name,Label,Freespace,Capacity | Format-List
$class = ($c.cimclass.cimclassname.split("_")[1])
$fragments+= $vol | ConvertTo-Markdown -precontent "## $class"

#processor
$cpu = Get-CimInstance win32_processor -ov c | 
Select-Object DeviceID,Name,Caption,MaxClockSpeed,*CacheSize,NumberOf*,SocketDesignation,*Width,Manufacturer
$class = ($c.cimclass.cimclassname.split("_")[1])
$fragments+= $cpu | ConvertTo-Markdown -PreContent "## $class"

#memory
$mem = Get-CimInstance win32_physicalmemory -ov c| Select-Object BankLabel,Capacity,DataWidth,Speed
$class = ($c.cimclass.cimclassname.split("_")[1])
$fragments+= $mem | ConvertTo-Markdown -precontent "## $class"

#networkadapter
$net = Get-NetAdapter -Physical -ov c | Select-Object Name,InterfaceDescription,LinkSpeed
$class="NetworkAdapter"
$fragments+= $net | ConvertTo-Markdown -precontent "## $class"

<#
#system drivers
$sysdrv = Get-CimInstance win32_systemdriver -ov c -filter "State='running'" | 
Select-Object Name,Description,State,StartMode,Started,Pathname,ServiceType | Sort State,Caption
$class = ($c.cimclass.cimclassname.split("_")[1])
$fragments+= $sysdrv | ConvertTo-Markdown -precontent "## $class"
#>

$fragments+= ConvertTo-Markdown -postcontent "_report run $(Get-Date)_"

$fragments | out-file -FilePath $filepath

The final markdown isn’t always perfect so expect to make some minor adjustments.

And here is one more example of creating a more complex markdown document.

. C:\scripts\Convertto-Markdown.ps1

$computers = "srv1","srv2","srv4"
$Title = "System Report"
$footer = "_report run $(Get-Date) by $($env:USERDOMAIN)\$($env:USERNAME)_"

$sb =  {
$os = get-ciminstance -classname win32_operatingsystem -property caption,lastbootUptime
[PSCustomObject]@{
    PSVersion = $PSVersionTable.PSVersion
    OS = $os.caption
    Uptime = (Get-Date) - $os.lastbootUpTime
    SizeFreeGB = (Get-Volume -DriveLetter C).SizeRemaining /1GB
}
}

$out = Convertto-Markdown -title $Title -PreContent "Here is the system summary information you requested."
foreach ($computer in $computers) {
 $out+= Invoke-command -scriptblock $sb -ComputerName $computer -HideComputerName |
 Select-Object -Property * -ExcludeProperty RunspaceID |
 ConvertTo-Markdown -PreContent "## $($computer.toUpper())"
}
$out += ConvertTo-Markdown -PostContent $footer
$out | set-content c:\work\report.md

I hope you’ll give the function a try and let me know what you think. And if you want to share any online tutorials for learning basic markdown, that would be terrific. Enjoy!

---

---