GitHub Flavored Markdownをローカルでプレビューしたい

Feb 28, 2023 · 2 min read · GitHub ·

日々GitHub上で管理されたファイルを編集していて欠かせないことの1つに「Pull Requestを作る」があります。
Pull Request（以下プルリク）の説明文はMarkdown記法をサポートしているので、箇条書きやWeb上にあるドキュメントへリンクなどを気軽に書くことができます。

ところで、プルリクの説明文やいわゆるREADME.mdのようなMarkdownで書かれた内容は直接GitHub上で表示されるのではなく¹、別途HTMLに変換されて表示されます。プルリク作成の画面ではMarkdownの編集モードとPreviewモードが別タブで用意されているのですが、本ブログ内でたびたび登場するVSCodeなどのエディタではMarkdown形式の内容とその描画結果を横に並べて確認しながら編集が可能なので、プレビューモードと編集モードを都度マウスで切り替えることが手間に感じることがあります。

プルリクをローカルで作る

そこで、プルリクの説明文をローカル環境で作成することにしました。…といっても、例えば body.md 等適当に命名したファイルに説明文を書き、都度プレビューするのみです。
このファイルの中身をプルリクの説明文にそのまま転記してもよいのですが、GitHub CLI を使うと以下のコマンドでブラウザなしにプルリクが作成できるので重宝しています。

# -F で説明文を記載したファイル名を指定
# --reviewerでレビュワーも併せて指定できる
$ gh pr create --title "プルリクタイトル" -F ./body.md --reviewer someone

GitHub Flavored Markdownもプレビューしたい

多くの場合前述の方法で問題ないのですが、不満に感じることが出てきました。それは、GitHub Flavored Markdownがプレビューできない場合があることです。

GitHubのMarkdownは厳密にはGitHub Flavored Markdownと呼ばれるMarkdownの方言に従い、いくつかの拡張構文があります。

基本的な内容はこちらにまとまっていて、私が個人的によく使うのは「プルリクエストの参照」です。他にもこちらで触れられている「タスクリスト」（チェックボックス）をよく使いますが、いずれも少なくとも202301末時点のVSCodeの標準のMarkdownプレビュー機能ではサポートされておらず、プレビューできません。

例えば以下のように記載した際、GitHub上では #1 が1番のプルリクへのリンクになりますが、（当然ではありますが）VSCodeではリンクにはならずそのまま出力されます。

過去のプルリク、 #1 では...

これをリンクとして表示されるか確認したいと思っていたところで GitHubが公開しているWeb APIの中にMarkdown API（20221128現在）を見つけました。
このAPIは

Use the REST API to render a markdown document as an HTML page or as raw text.

とあるように、Markdown形式の内容を入力することで対応するHTMLファイルを返してくれます。

使ってみましょう。
GitHub APIはcURL等で実行できますが、前述のGitHub CLIを使うと認証情報の入力を省略して実行できます。

gh api -X POST \ 
    -H "Accept: application/vnd.github+json" \
    /markdown \
    -F mode="gfm" \
    -F text="$(cat ./body.md)" \
    -F context="{owner}/{repo}"

このAPIでは mode="gfm" で GitHub Flavored Markdownとして処理することを指定します。

さらに、context で対象とするリポジトリを指定します。Markdown上で #1 と記載したときに、どのリポジトリのプルリクか、というコンテキストを付与するものです。

ここで {owner}/{repo} というのは GitHub CLIの機能で、ドキュメントより、

placeholder values “{owner}”, “{repo}”, and “{branch}” get populated with values from the repository of the current directory;

作業ディレクトリのリポジトリの情報をもとに自動で適切な値を使ってくれます。例えば context="yota/helloworld" のように都度明示するより汎用的ですね。

実行してみましょう。

$ cat body.md
過去のプルリク、 #1 では...
$ gh api -X POST     -H "Accept: application/vnd.github+json"  /markdown -F mode='gfm' -F text="$(cat ./body.md)" -F context="{owner}/{repo}"
<p dir="auto">過去のプルリク、 <a class="issue-link js-issue-link"  data-url="<リポジトリURL>/issues/1" data-hovercard-type="pull_request" data-hovercard-url="/<リポジトリ名>/pull/1/hovercard" href="<リポジトリURL>/pull/1">#1</a> では...</p>

少しわかりづらいですが、 #1 がプルリクのURLへの a 要素になっています。ブラウザで見てみると、

#1 がリンクになっていますね。 ²

これにより、都度 gh api を実行して、HTMLの描画を都度確認できる環境を用意すれば手軽にGitHub Flavored Markdownの内容を確認できるようになりました。

「HTMLの描画を都度確認できる環境」を用意している時点で「ローカル」の範疇を超えそうな勢いですが、#1 がリンクになっているか、といった程度であればブラウザで見ずともHTMLの状態でも十分確認できる上、ターミナルやエディタから1、2個のショートカットでブラウザで表示できるのでよしとしています。

ちなみに、GitHub CLIにはエイリアス機能があり、上記のコマンドを登録できます。
具体的には、

# エイリアス名mdとして登録
$ gh alias set md 'api -H "Accept: application/vnd.github+json" -X POST /markdown -F text="$1" -F mode="gfm" -F context="{owner}/{repo}"'

としておくことで、