入れ子になった箇条書き、いくつかのコードブロック、2つのアプローチを比較する表を含むREADMEを書きます。エディタ内のプレーンテキストとしては問題なさそうに見えます。ところがGitHubにプッシュすると、表の位置がずれ、コードブロックの1つが正しく閉じられておらず、余分な空行のせいで番号付きリストが途中で1から再スタートしています。今度はフォーマットを直すためだけに小さな修正コミットをプッシュすることになります。
マークダウンは基本的な整形であれば記憶だけで書けるほどシンプルですが、表、入れ子になったリスト、コードフェンスにはそれぞれ小さな構文の癖があり、レンダラーによって微妙に異なります。GitHub Flavored MarkdownはCommonMarkと同一ではなく、CommonMarkもあなたの静的サイトジェネレーターが使っているものと同一ではありません。「頭の中では正しく見える」と「ページ上で正しくレンダリングされる」の間のギャップこそ、ライブプレビューがまさにその価値を発揮する場所です。
確認のためにコミットするのが悪いワークフローである理由
READMEがどうレンダリングされるかを見るためだけにコミットをプッシュし、壊れた表を直すためにまた別のコミットをプッシュし、さらにその修正のための修正をプッシュすることは、実際の内容とは無関係な整形上のノイズでコミット履歴を散らかしてしまいます。またそれは、プレビューの1サイクルごとにプッシュとページの再読み込みと同じだけの時間がかかることも意味します——遅すぎて確認するのをやめてしまい、見た目が良いことを願うだけになりがちです。
入力しながらレンダリングされた出力を確認
Bellowsには、生のマークダウンを貼り付けたり入力したりすると整形された出力をレンダリングするマークダウンプレビューツールが含まれています。見出し、リスト、表、リンク、コードブロックはすべて即座にレンダリングされるため、コミットに紛れ込む前に整形ミスを発見できます。
READMEとPRの説明を書く
プルリクエストの説明とREADMEファイルは、多くの場合レビュアーや新しいコントリビューターが最初に読むものです。提出する前に見出し、チェックリスト、リンクされた画像が正しくレンダリングされることを確認しておけば、「フォーマットを直してもらえますか」というコメントのやり取りを1往復減らせます。
オフラインでドキュメントを執筆する
飛行機の中やインターネットが不安定な場所でドキュメントを書くからといって、整形が正しくレンダリングされているのを確認することを諦める必要はありません。ローカルのプレビューツールは、接続の有無にかかわらず同じように動作します。