PowerShell Core 6.1 Preview.4からMarkdownを扱う以下のコマンドレットが追加されました。
ConvertFrom-MarkdownShow-MarkdownGet-MarkdownOptionSet-MarkdownOption
これらのコマンドレットを使うとMarkdownのドキュメントを解析し、HTMLまたはコンソールに表示することができる様になります。
実装方法は前回説明したThreadJobとは異なりPowerShell Core本体(Microsoft.PowerShell.Utility.dll)に実装されています。
このためWindows PowerShellでこれらのコマンドを利用することはできません。
また内部的にMarkdigを利用しています。
機能説明
まずは各コマンドの機能説明をします。
ConvertFrom-Markdown
Markdownのファイルまたは文字列を読み込みMicrosoft.PowerShell.MarkdownRender.MarkdownInfo型のオブジェクトに変換します。
Microsoft.PowerShell.MarkdownRender.MarkdownInfo型のオブジェクトは後述のShow-MarkdownでHTMLまたはコンソールに表示します。
-Pathおよび-LiteralPathを指定した場合はファイルから内容を読み込みます。
文字コードはUTF-8であることが期待されており-Encodingパラメーターはありません。
ConvertFrom-Markdown -Path .\sample.md
(sample.mdの内容は以下)
# ヘッダ1 __マークダウン__ の _サンプル_ です。 ## ヘッダ2 * Hello * World ### ヘッダ3 1. Hello 1. PowerShell #### ヘッダ4 うちのブログ * [しばたテックブログ](https://blog.shibata.tech) ##### ヘッダ5 \``` # コードブロックのサンプル Write-Output "Hello" \``` ###### ヘッダ6 > 引用文です。
既定ではMarkdownはHTMLに変換されます。
-AsVT100EncodedStringパラメーターを付けるとコンソール表示用にVT100エスケープシーケンスで修飾された文字列に変換されます。
ConvertFrom-Markdown -Path .\sample.md -AsVT100EncodedString
また、パイプラインから文字列およびSystem.IO.FileInfo型のオブジェクトを受け取ることも可能です。
@" # ヘッダ1 __マークダウン__ の _サンプル_ です。 ## ヘッダ2 * Hello * World "@ | ConvertFrom-Markdown
Get-ChildItem .\sample.md | ConvertFrom-Markdown
Show-Markdown
ConvertFrom-Markdownで生成したオブジェクトをコンソールもしくはWEBブラウザに表示します。
個人的にちょっとイケてないと思うのですが、このコマンドはHTMLが既定のConvertFrom-Markdownとは逆でコンソール表示が既定となります。
このため以下の様にConvertFrom-MarkdownとShow-Markdownの組み合わせでNGとなるケースが出てしまいます。
# OK ConvertFrom-Markdown -Path .\sample.md -AsVT100EncodedString | Show-Markdown # NG : Show-Markdownは既定でコンソール表示なため、ConvertFrom-Markdownで-AsVT100EncodedStringの指定が必要 ConvertFrom-Markdown -Path .\sample.md | Show-Markdown
HTMLを表示する場合は-UseBrowserパラメーターを指定してやる必要があり、名前の通り既定のブラウザでHTMLとなったMarkdownの文章を表示します。
# OK ConvertFrom-Markdown -Path .\sample.md | Show-Markdown -UseBrowser
【2018/09/11追記】
最初にPreview.4でこの機能がリリースされてからShow-Markdownが使いにくいというフィードバックがあり、次のリリースのRC.1ではShow-Markdownに-InputObject、-Path、-LiteralPathパラメーターが追加され、このコマンドで直接Markdownを扱うことができる様に改善されています。
# PowerShell Core 6.1 RC.1より Show-Markdown -Path .\sample.md
# PowerShell Core 6.1 RC.1より @" # ヘッダ1 __マークダウン__ の _サンプル_ です。 ## ヘッダ2 * Hello * World "@ | Show-Markdown
【追記ここまで】
Get-MarkdownOption
Markdownの変換に関する各種設定を表示します。
Get-MarkdownOption
現時点ではMarkdownの各要素をコンソール表示する際の色指定のみ存在します。
今後設定が増える可能性は高いと思われます。
Set-MarkdownOption
Markdownの変換に関する各種設定を設定します。
Set-MarkdownOption -Header1Color "[4;92m"
PowerShellではありがちですが、このコマンドで設定した内容は永続化されません。
永続化したい場合はプロファイルにコマンドを記述してください。
何故この機能が追加されることになったのか？
ここからは補足的な内容となります。
興味のある方はご覧ください。
今回追加されたMarkdownに関わる機能は以下Issueを発端とし、
RFC(Native Markdown Rendering)を経て採用、機能追加されています。*1
このRFCによれば、
Motivation
Markdown is a common authoring format used by the community. There is no easy way in PowerShell to visualize a markdown document on console. Since the PowerShell help is authored in markdown, these components will be used for rendering help content.
とあり、PowerShell TeamとしてはMarkdownで新しくヘルプドキュメントを作り直したい展望があり、そのためにPowerShell内部でネイティブにMarkdownを解析しレンダリングする機能が必要になったことが根底にあります。
すこし話が逸れますが、PowerShellのヘルプドキュメントはコードコメントかMAMLで書く必要があり、特にMAMLの記述が非常に面倒であるという現状があります。
(私もMAMLは全然書けませんし、正直書く気も起きません...)
この現状を打開するためにPlatyPSといったプロジェクトが存在し、ヘルプドキュメントのMarkdown化は以前から検討されていました。
まだヘルプドキュメントのMarkdown化は実現していませんが、今回の機能追加を経て順次成されていくのかな？と思います。
現状の課題と展望
先述のRFCを見ればわかりますが、現在はRFCにある機能が全て実装されていませんし、実装されている機能にも幾つか細かいバグがあります。
他にも
「ConvertFrom-MarkdownがあるならConvertTo-Markdownも欲しい。」
といった要望や、
「Markdown関連の機能をモジュールとして切り出すべきでは？」
といった意見もあり、まだまだ課題が多いのが正直なところでしょう。
これらの課題がどう解決されるかはまだ何とも言えません。
最後に
ちょっと長くなりましたがこんな感じです。
機能のあり方に課題は残るものの、利用者目線で見ればこの点を気にする必要は無いでしょう。
PowerShell Teamの思惑を抜きにしてもMarkdownはよく使うものですし追加された機能を活用できる状況は多いのではないかと思います。
*1:RFCを採用したなら3-Experimentalから4-Experimental-Acceptedに移動すべきなのですが、なぜか移動されておらずその理由も不明です... 2018/0913に5-Finalに移動されてました。
