README.mdをGitHubへ公開する前に、見出し・表・コード・リンク・画像・タスクリストを確認する方法を解説。Viewerでの一次確認とGitHubでの最終確認を分けます。
目次（8）
README.mdを書いたあと、GitHubへpushする前に見た目を確認したいことがあります。
このとき重要なのは、事前確認とGitHub上の最終確認を分けることです。README.mdは一般的なMarkdownとして事前プレビューできますが、GitHubではGitHub Flavored Markdown（GFM）とGitHub固有の処理が使われるため、別のViewerで完全に同じ表示を再現できるとは限りません。
この記事では、公開前にどこまで確認できるかと、GitHub側で最後に確認すべき項目を整理します。
先に結論：ブラウザで一次確認し、最後はGitHubで確認する
README.mdの見出し、表、リスト、コードブロックなどは、Markdown Viewerで公開前に一次確認できます。そこで大きな構文崩れを直し、実際にリポジトリへ置いたあとはGitHub自身の表示で最終確認するのが分かりやすい流れです。
oka-projectのMarkdown Viewerは、.mdファイルやMarkdownテキストをブラウザ上でプレビューできる無料・登録不要のツールです。入力内容はブラウザ内で処理し、サーバーへ送信・保存しない構成にしているため、未公開のREADMEをGitHubへ置く前に読みやすさや基本構文を確認する一次プレビューに使えます。
ただし、GitHub固有の表示を完全再現するツールではありません。最終的なREADMEの表示はGitHubで確認します。
README.mdで公開前に確認したいもの
READMEはプロジェクトの入口になることが多いため、文章の内容だけでなく、構造が意図どおり見えるかを確認しておくと安心です。
特に確認したいのは、見出し階層、コードブロック、表、リンク、画像、タスクリストです。
文章だけのREADMEなら崩れにくいですが、セットアップ手順や比較表、コマンド例が増えるほど、ソースだけでは完成形を想像しにくくなります。
1. 見出しの階層を確認する
READMEでは、# の数で見出し階層を作ります。
# プロジェクト名
## インストール
### 必要な環境
## 使い方
ソースだけを見ていると見落としやすいのが、見出し階層の飛びや、文章量に対して見出しが細かすぎる構成です。
プレビューすると、README全体の流れが視覚的に分かります。最初に大見出しを増やしすぎず、「概要 → インストール → 使い方 → 補足」のように情報を追えるかを確認します。
2. コードブロックが途中で切れていないか確認する
READMEではインストールコマンドや設定例を載せることが多くあります。
```bash
npm install
npm run dev
```
バッククォートの閉じ忘れがあると、その後の文章までコードブロックとして表示されることがあります。
コードが長い場合は、プレビューで「どこからどこまでがコードになっているか」を確認する方が早く見つけられます。
3. 表は列数とパイプを確認する
GitHub Flavored Markdownでは表が利用できます。
| 項目 | 内容 |
| --- | --- |
| 対応OS | Windows / macOS |
| ライセンス | MIT |
特に崩れやすいのは、見出し行と区切り行の列数が合っていない場合や、セル内にパイプ | をそのまま書いた場合です。
GFM仕様では、見出し行と区切り行のセル数が一致しなければ表として認識されません。また、セル内にパイプを含めたい場合はエスケープが必要です。
表のトラブルを症状別に確認したい場合は、Markdownの表が崩れる・表示されない原因で詳しく整理しています。
4. タスクリストはGitHub固有の使われ方も確認する
GitHubでは、次のようなMarkdownをタスクリストとして表示できます。
- [x] 初期設定
- [ ] ドキュメント追加
- [ ] リリース
GFMではタスクリストが拡張機能として定義されています。またGitHub上では、issueやpull requestなどと組み合わせた固有の表示・機能もあります。
そのため、一般的なMarkdown Viewerでチェックボックスの形を確認できても、GitHub上での動作や周辺UIまで同じとは限りません。
5. 相対リンクはリポジトリに置いた後の確認が必要
READMEでは、同じリポジトリ内のファイルや画像へ相対リンクを張ることがあります。
[詳しい手順](docs/setup.md)
このリンクが正しく解決されるかは、READMEが置かれるパスやリポジトリ構成に依存します。GitHub公式では、相対リンクや画像パスを現在のブランチに基づいて変換すると説明しています。
ローカルのViewerではMarkdown構文としてリンクになっていることは確認できますが、GitHub上で目的のファイルへ正しく遷移するかはGitHubで確認する必要があります。
画像についても同様です。相対パス、ブランチ、ファイル名の大文字・小文字など、Markdownそのもの以外の条件が関係します。
GitHubと一般的なMarkdown Viewerで表示が違う理由
GitHubではGitHub Flavored Markdownが使われています。
GFMはCommonMarkを基礎にしながら、表、タスクリスト、取り消し線、自動リンクなどの拡張を持っています。さらにGitHub.comでは、GFMからHTMLへ変換したあとにもセキュリティやサイト表示のための追加処理が行われます。
つまり、README.mdには大きく2段階あります。
Markdownとして構文が成立しているかは汎用Viewerでも確認できます。一方、GitHub上で最終的にどう見えるかはGitHub自身で確認する必要があります。
この2つを同じものとして扱わないことが重要です。
GitHubへ上げる前の一次確認手順
まだ公開したくないREADMEを確認する場合は、ファイルだけをブラウザで開いて確認できます。
- Markdown Viewerを開く
README.mdを選ぶ- 見出し階層を上から確認する
- 表とコードブロックが崩れていないか見る
- リンクの表示文字列やURLを確認する
- 修正後、再度プレビューする
この段階の目的は、GitHubを完全再現することではありません。READMEを公開する前に、明らかな構文ミスや読みづらさを減らすことです。
Markdown全般をブラウザで確認する方法については、Markdownをブラウザだけでプレビューする方法も参考になります。
GitHubへ置いた後に最終確認する
リポジトリへ反映したあとは、GitHub上でREADMEを開いて確認します。
ここでは特に、相対リンク、画像、表、タスクリスト、コードブロック、見出しから生成されるリンクなどを見ます。
GitHub固有の機能を多く使っているREADMEほど、この最終確認が重要です。
「ブラウザViewerで正しく見えたからGitHubでも必ず同じ」と考えるのではなく、Viewerは一次確認、GitHubは公開環境の確認と役割を分けます。
未公開READMEをオンラインツールで確認するときの注意
READMEには、公開前のURL、構成案、内部向けのセットアップ情報などが含まれることがあります。
Webツールを使う場合は、ファイルをサーバーへアップロードして処理するのか、ブラウザ内で処理するのかを確認します。
oka-projectのMarkdown Viewerでは入力内容をブラウザ内で処理し、サーバーへ送信・保存しません。外向き通信もCSPで制限しています。仕組みについては、ブラウザ完結ツールの「送信しない」を、約束ではなく構造にするで説明しています。
ただし、組織の非公開情報を扱う場合は、ツールの方式だけでなく社内ルールも優先してください。
READMEの確認で迷ったら、この順番で見る
公開前にすべてを細かく確認しようとすると時間がかかります。
最初は、タイトルと見出し階層が読みやすいかを確認します。次に、コードブロックと表が途中で崩れていないかを見る。その後でリンクと画像を確認し、GitHubへ反映した段階で相対リンクやGitHub固有表示を最終チェックする流れが扱いやすいです。
構文の問題と公開環境の問題を分けることで、修正箇所を特定しやすくなります。
よくある質問
ブラウザのViewerで正しく見えれば、GitHubでも同じ表示になる？
限りません。GitHubではGFMとGitHub固有の追加処理が使われるため、汎用Viewerは完全なGitHubプレビューではありません。Viewerは一次確認、GitHubは公開環境の確認と役割を分けます。
コードブロックの後ろの文章まで全部コードになってしまうのは？
バッククォートの閉じ忘れが原因のことが多いです。プレビューで「どこからどこまでがコードになっているか」を確認すると早く見つけられます。
相対リンクが正しいかは公開前に確認できる？
Markdown構文としてリンクになっていることはViewerで確認できますが、目的のファイルへ正しく遷移するかはREADMEが置かれるパスやリポジトリ構成に依存します。GitHub上で確認する必要があります。
未公開のREADMEをオンラインツールで開いても大丈夫？
ファイルをサーバーへアップロードして処理するのか、ブラウザ内で処理するのかを確認します。oka-projectのMarkdown Viewerは入力内容をブラウザ内で処理し、サーバーへ送信・保存しませんが、組織の非公開情報を扱う場合は社内ルールを優先してください。
まとめ
README.mdはGitHubへ公開する前に、一般的なMarkdownとしてプレビューできます。見出し、表、コードブロックなどの基本的な崩れを先に直しておけば、GitHubへ反映した後の確認項目を減らせます。
ただしGitHubではGFMと追加処理が使われるため、汎用Viewerは完全なGitHubプレビューではありません。
Markdown Viewerで一次確認し、GitHubで最終確認する。 この2段階に分けるのが、READMEを公開前に確認するシンプルな方法です。