Powershell: Showing markdown with new commands is harder than it should be

[rkeithhill]

When I first tried to use the new markdown commands to show a markdown file, it seemed obvious to me that I'd just run:

# Expected:
Show-Markdown .\README.md

but that doesn't work. You have to execute this instead:

# Actual:
ConvertFrom-Markdown -path .\README.md -AsVT100EncodedString | Show-Markdown

It seems to me that Show-Markdown should have a Path parameter set so that you can simply specify the path to a markdown file to be shown.

Environment data

> $PSVersionTable
Name                           Value
----                           -----
PSVersion                      6.1.0-preview.4
PSEdition                      Core
GitCommitId                    6.1.0-preview.4
OS                             Microsoft Windows 10.0.17134
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

[SeeminglyScience]

In the same vein I would expect the following to work

'# My Header' | Show-Markdown

When instead this is required

'# My Header' | ConvertFrom-Markdown -AsVT100EncodedString | Show-Markdown

[oising]

Agreed. I think this is not intuitive and is probably a leaky abstraction. The fact that markdown ascii/utf8 gets converted to ecma48 / vt100/102/220 control sequences seems like a detail nobody should know nor care about. Note that the console isn't even strictly vt100 (it also supports colour which isn't part of vt100).

I'd suggest keeping the convertfrom-markdown cmdlet and shipping show-markdown as a wrapper function that invokes it and dumps out the VT string. Please add proper positional hints to the parameters too.

[Jaykul]

Agreed: if ConvertFrom has a -AsAnsiEncodedString then we should not need Show

[SteveL-MSFT]

Show-Markdown also supports HTML rendered markdown

[oising]

Some more comments from a blogger here about the quirks and annoyances: https://ephos.github.io/posts/2018-8-1-PowerShell-Markdown

[felixfbecker]

Imo the VT encoded string should not be exposed at all. Colorising is a formatting concern, and formatting belongs into Format.ps1xml files, not into pipeline objects and properties.