【GitHub】Markdown形式のREADME.mdをプレビューしながら編集する




GitHubを使うとき、プログラムの説明を書くREADME.mdを書いている方がほとんどかと思います。このREADME.mdですがMarkdownという形式でしてエディターやブラウザで完成形を確認することが出来ません。

一応、GitHubのウェブサイトでプレビューの機能があるのですが、ローカルのワーキングツリーにあるREADME.mdを編集してからリモートにプッシュしたいという人も多いと思います。

そこで、今回はMarkdown形式のファイルをプレビューしながら編集する手順を紹介します。超簡単です。

僕の使っているOSはMacOS Mojave 10.14.5です。pipが必要なので、ご自分のOSに適した手順でインストールしておいてください。

インストール方法

pipを使ってgripというパッケージをインストールします。

pip install grip

使用方法

まずターミナルを立ち上げます。

使えるオプション

macbook@MacBookPro grip --help
Usage:
  grip [options] [<path>] [<address>]
  grip -V | --version
  grip -h | --help

Where:
  <path> is a file to render or a directory containing README.md (- for stdin)
  <address> is what to listen on, of the form <host>[:<port>], or just <port>

Options:
  --user-content    Render as user-content like comments or issues.
  --context=<repo>  The repository context, only taken into account
                    when using --user-content.
  --user=<username> A GitHub username for API authentication. If used
                    without the --pass option, an upcoming password
                    input will be necessary.
  --pass=<password> A GitHub password or auth token for API auth.
  --wide            Renders wide, i.e. when the side nav is collapsed.
                    This only takes effect when --user-content is used.
  --clear           Clears the cached styles and assets and exits.
  --export          Exports to <path>.html or README.md instead of
                    serving, optionally using [<address>] as the out
                    file (- for stdout).
  --no-inline       Link to styles instead inlining when using --export.
  -b --browser      Open a tab in the browser after the server starts.
  --api-url=<url>   Specify a different base URL for the github API,
                    for example that of a Github Enterprise instance.
                    Default is the public API: https://api.github.com
  --title=<title>   Manually sets the page's title.
                    The default is the filename.
  --norefresh       Do not automatically refresh the Readme content when
                    the file changes.
  --quiet           Do not print to the terminal.

詳細はGitHubの公式ページをご確認ください。

プレビューしてみる

プレビューしたいファイルを相対パスか絶対パスで指定します。

grip ~/README.md

するとこのような表示が出ます。

 * Serving Flask app "grip.app" (lazy loading)
 * Environment: production
   WARNING: Do not use the development server in a production environment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://localhost:6419/ (Press CTRL+C to quit)

ここに書いてあるローカルパスhttp://localhost:6419/にアクセスするとプレビュー結果を見ることが出来ます!最後に80などの数字を指定すると該当するポートを割り振ることが出来ます。

grip ~/README.md 80

ちなみに、プレビューを見ながらエディターでファイル(今回はREADME.me)を開いて編集する場合、Command+Cで上書き保存したタイミングでプレビューも自動更新されます。とても便利ですね!