GitHubユーザーの中には、READMEファイルって最初に勝手に作成されるファイルくらいの認識で、実際に書いたことはないという方もいらっしゃるのではないでしょうか。

本記事では、ぜひ活用したいREADMEの作成方法から使い方、実際の記述方法についてご紹介していきます。

GitHubのREADMEファイルとは


GitHubに限らずですが、Gitでリポジトリを作成する際にREADMEファイルを追加するかしないか決めることが出来ます。

このREADMEファイルには様々な内容が記述され、プロジェクト毎に異なります。

ポテパンダの一言メモ

READMEファイルをリポジトリ作成時点で追加しなくても、後ほど設定することも可能です。

READMEファイルの役割

READMEファイルは主に「システムの概要」「ツールの使い方」「インストール方法」などが記述されます。

リポジトリに格納されたソースコードを利用したり、参照する前に読んでほしい内容が記載されます。

READMEファイルの記述法

READMEファイルは「マークダウン記法」で記述されるファイルです。

マークダウン記法では文字の装飾を簡単に行うことが出来るため、読みやすいドキュメントを効率的に作成することが出来ます。

HTMLなどの「マークアップ言語」を簡略化して、より簡単に記述出来るようにしたのが「マークダウン」と呼ばれる記述法です。

GitHub上でREADMEファイルを作成してみよう


ここからは実際にGitHub上でREADMEファイルを作成する手順についてご紹介していきます。

リポジトリの作成

リポジトリを新規で作成する際、READMEファイルを作成するかどうか選択することが可能です。


GitHubにログインした状態で「Repositories」タブから「New」ボタンをクリックします。


リポジトリの設定画面で赤枠の「Add a README file」のチェックボックスを選択することで作成されます。


作成した時点ではREADMEにリポジトリ名のみが記載されています。

リポジトリ作成後のREADME追加


リポジトリ作成時点でREADMEファイルを作成しなかった場合、リポジトリの「Code」タブを開くと「Add a README」ボタンが表示されているのでクリックします。


READMEファイルの編集画面に切り替わるので、任意の内容に編集してコミットすれば追加完了です。


デフォルトの状態のままコミットすると、リポジトリの名前だけが記載されたREADMEが表示されます。

GitHubでREADMEファイルを編集してみよう


では実際にGitHub上のエディタを使用して、READMEファイルの記述方法についてご紹介していきます。

ポテパンダの一言メモ

サンプルではGitHub上のエディタで編集していきますが、ローカルのエディタで編集してGitHubにプッシュする方法でも編集することが可能です。

マークダウン方式の書き方

マークダウン方式でよく利用する装飾の書き方を実際の表示内容と合わせて確認していきましょう。

見出し

見出しは「#」の数によって「h1」から順に指定することが出来ます。

# 見出し1
## 見出し2
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6


READMEファイルに記述してコミットすると下記画像のように表示されます。

改行

マークダウン方式で改行を入れる場合、READMEの記述に空白行を加えるだけで反映されます。

文章を改行します。

マークアップに記述した形式のまま表示されます。

コミットして表示内容を確認してみましょう。

強調表示

強調表示には「*」または「_」を指定することで設定可能です。

*強調*

_これも強調_

**もっと強調**

__同じくもっと強調__


コミットして内容を確認すると文字が強調され表示されています。

リンク

文字列をリンク形式にしたい場合、下記の記述方法となります。

[文字列](URL)

こちらもコミットして表示内容を確認してみましょう。

画像の挿入

READMEには文字列だけでなく、画像を挿入することも可能です。

まず表示したい画像をGitHub上のリポジトリに追加します。


リポジトリの画面から「Add file」ボタンをクリックして、「Upload files」を選択します。


画面中央の赤枠にアップロードしたいファイルをドラッグ&ドロップするか「choose your files」のリンクからファイルを選択します。

アップロードが完了したら画面下部の「Commit changes」ボタンをクリックします。


リポジトリの一覧にアップロードしたファイルが表示されています。

画像がアップロード出来たらREADMEファイルの編集に移ります。

READMEファイルには下記の記述で画像の指定を実施することが可能です。

![画像名](相対パスまたは絶対パス)


READMEファイルと同階層に画像ファイルを格納したので、「./ファイル名」で相対パス指定しました。

コミットしてREADMEに画像が表示されるか確認してみましょう。

READMEファイル内に指定した画像が表示されていることを確認出来ます。

GitHubのProfile用READMEを作成してみよう


ここまでREADMEファイルの作成方法や記述法について説明してきましたが、GitHubではアカウントのProfile情報をREADMEファイルで作成することも可能です。

READMEコンテンツの表示箇所


GitHubでは、アカウント情報を開いた右側の赤で塗りつぶした箇所にREADMEファイルで記載した内容を表示することが出来ます。

Profile用READMEの作成方法

Profile用のREADMEを作成するためには、アカウント名と同じリポジトリを作成する必要があります。


「Repositories」タブに移動して、「New」ボタンをクリックします。


赤枠の「Owner」と「Repository name」が同じになるように設定します。

リポジトリ作成のタイミングでREADMEファイルも作成しておきましょう。


リポジトリの作成が完了すると、上記画像のような初期画面が表示されます。


GitHubアカウントのトップページに戻ると初期状態のREADMEファイルの内容が表示されていることが確認出来ます。

Generatorでサンプルを作成してみよう

Profile READMEを一から作成するのも大変だし、簡単にシンプルなREADMEを作ってみたいという方には「GitHub Profile README Generator」などのツールも使ってみてください。


カテゴリ分けされた入力用テキストが表示されるので、任意の項目を埋めていきます。

画面下部にある「Generate README」ボタンをクリックすると下記のコードのようにマークダウン形式で出力されます。

<h1 align="center">Hi 👋, I'm potepan</h1>
&nbsp;
<h3 align="center">A passionate frontend developer from Japan</h3>
- 🔭 I’m currently working on **Potepan style** - 🌱 I’m currently learning **Python** - 💬 Ask me about **vue**
<h3 align="left">Languages and Tools:</h3>
&nbsp;
<p align="left"><a href="https://expressjs.com" target="_blank" rel="noopener"> <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/express/express-original-wordmark.svg" alt="express" width="40" height="40" /> </a> <a href="https://www.java.com" target="_blank" rel="noopener"> <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/java/java-original.svg" alt="java" width="40" height="40" /> </a> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript" target="_blank" rel="noopener"> <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/javascript/javascript-original.svg" alt="javascript" width="40" height="40" /> </a> <a href="https://www.mysql.com/" target="_blank" rel="noopener"> <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/mysql/mysql-original-wordmark.svg" alt="mysql" width="40" height="40" /> </a> <a href="https://www.oracle.com/" target="_blank" rel="noopener"> <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/oracle/oracle-original.svg" alt="oracle" width="40" height="40" /> </a> <a href="https://www.php.net" target="_blank" rel="noopener"> <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/php/php-original.svg" alt="php" width="40" height="40" /> </a> <a href="https://www.postgresql.org" target="_blank" rel="noopener"> <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/postgresql/postgresql-original-wordmark.svg" alt="postgresql" width="40" height="40" /> </a> <a href="https://reactjs.org/" target="_blank" rel="noopener"> <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/react/react-original-wordmark.svg" alt="react" width="40" height="40" /> </a> <a href="https://www.typescriptlang.org/" target="_blank" rel="noopener"> <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/typescript/typescript-original.svg" alt="typescript" width="40" height="40" /> </a> <a href="https://vuejs.org/" target="_blank" rel="noopener"> <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/vuejs/vuejs-original-wordmark.svg" alt="vuejs" width="40" height="40" /> </a></p>
&nbsp;


実際にアカウント画面で確認すると画像のように表示されます。

さいごに: GitHubでプロジェクトを共有するならREADMEファイルを活用しよう


本記事では、GitHubでのREADMEファイルの作成方法から実際の記述法までご紹介してきました。

GitHubの情報を外部公開する場合はもちろん、自分以外の開発者とプロジェクトを共有するような場合には、READMEを活用してシステムの取り扱い方法を理解してもらうのは基本です。

マークダウン方式の記述には最初はなれないかも知れませんが、簡単に使いこなせる記述法ですので、ぜひたくさんのREADMEファイルを読みやすく作成してみてください。

エンジニアになりたい人に選ばれるプログラミングスクール「ポテパンキャンプ 」

ポテパンキャンプは卒業生の多くがWebエンジニアとして活躍している実践型プログラミングスクールです。 1000名以上が受講しており、その多くが上場企業、ベンチャー企業のWebエンジニアとして活躍しています。

基礎的な学習だけで満足せず、実際にプログラミングを覚えて実践で使えるレベルまで学習したいという方に人気です。 プログラミングを学習し実践で使うには様々な要素が必要です。

それがマルっと詰まっているポテパンキャンプでプログラミングを学習してみませんか?

卒業生の多くがWebエンジニアとして活躍

卒業生の多くがWeb企業で活躍しております。
実践的なカリキュラムをこなしているからこそ現場でも戦力となっております。
活躍する卒業生のインタビューもございますので是非御覧ください。

経験豊富なエンジニア陣が直接指導

実践的なカリキュラムと経験豊富なエンジニアが直接指導にあたります。
有名企業のエンジニアも多数在籍し品質高いWebアプリケーションを作れるようサポートします。

満足度高くコスパの高いプログラミングスクール「ポテパンキャンプ」

運営する株式会社ポテパンは10,000人以上のエンジニアのキャリアサポートを行ってきております。
そのノウハウを活かして実践的なカリキュラムを随時アップデートしております。

代表の宮崎もプログラミングを覚えサイトを作りポテパンを創業しました。
本気でプログラミングを身につけたいという方にコスパ良く受講していただきたいと思っておりますので、気になる方はぜひスクール詳細をのぞいてくださいませ。