GitHubのREADME.mdを書いてみた（マークダウン記法）
本ページはプロモーションが含まれています
GitHubで公開しているリポジトリを説明するもので「README.md」というものがあることを知りました。GitHub上で編集して公開することができるようなので、編集の流れを紹介します。
README.mdとは
GitHubの公式ドキュメントが参考になります（日本語）
以下、重要だと思ったところを一部抜粋します。
リポジトリにREADMEファイルを追加して、そのプロジェクトがなぜ有益なのか、そのプロジェクトで何ができるか、そのプロジェクトをどのように使えるかを他者に伝えることができます。
多くの場合、READMEはリポジトリへの訪問者が最初に目にするアイテムです。 通常、README ファイルには以下の情報が含まれています
- このプロジェクトが行うこと
- このプロジェクトが有益な理由
- このプロジェクトの使い始め方
- このプロジェクトに関するヘルプをどこで得るか
- このプロジェクトのメンテナンス者とコントリビューター
簡単にまとめると、プロジェクトの説明書のようなもので、どのようなもので利用する際にどのようなことに気をつけたほうが良いかが記載されているようです。
README.mdの追加手順
まずREADME.mdを追加したいリポジトリにアクセスします。まだリポジトリにREADME.mdを追加していない状態だど、キャプチャのように画面下部の赤枠の箇所に、[Add a README]と表示されているはずなので、選択します。
ページ遷移するとこのような画面が表示されます。この画面上で編集するようです。まずは[Preview]を選択してみましょう。
そうするとこのような感じになっているかと思います。前のページで[#リポジトリ名]となっていたところが見出しのようになっていました。これはマークダウン（Markdown）記法と呼ばれる方法で記述することでこのように装飾できるようです。
マークダウン（Markdown）記法って何？
全然馴染みがないので、調べてみました。
- 【マークダウン記法とは？】マークダウンの書き方を網羅的に解説（Backlogブログ）
- Markdown記法 チートシート（Qiita公式）
文章の先頭などに「#」や「*」をつけることで見出しなどを装飾することができるものということでした。Backlogブログの記事が非常にわかりやすいです。この記事を読んで今更ながら気づいたのですが、Backlogチケットを追加するときに見出しなどを装飾する方法がマークダウン記法でした。自分は前からちょこちょこ使ってたので、急にとっつきやすくなりました。
マークダウン記法でREADME.mdを書いてみた
参照しながらですが、マークダウン記法で「見出し」、「リスト」、「リンク」、「改行」をやってみました。以下のように記述するようでした。
- 見出し → 「#」
- リスト → 「*」
- リンク → 「[リンク表示テキスト](URL)」
- 改行 → 半角スペース2個
慣れるまで違和感ありそうですが、なんとなく雰囲気わかってきたので、少しずつ慣れていきたいと思います。
プレビューイメージ
README.mdを公開してみる
README.mdがかけたら画面下部の[Commit new file]を選択してください。
公開できたら、リポジトリの下部に今回作成した説明文が追加されているはずです。これで公開完了です。
まとめ
今回はGitHubで公開しているリポジトリの説明文にあたるREADME.mdを書いてみました。マークダウン記法と言われる書き方も新しく勉強することができましたのでこれから慣れていきたいと思います。Backlogのマークダウンの記事でも紹介されていましたが、マークダウン記法に慣れると、記事やメモをより早く見やすく書くことができるようになりそうです。SEの方などがマークダウン記法をよく利用されるのがなんとなくわかってきました。自分もマークダウン記法を勉強したいと思います！
