【GitHub】README -マークダウン記法-

2024/1/1 公開
# Git# GitHub# Markdown# README

GitHubでリポジトリを開いたときにぱっと目に入るREADME。 文字を強調したりリストを使ったり見やすくしたいのに、改行されなかったりインデントが適用されなかったりとなんかうまくいかない。 これまでその都度調べて試していましたが、いい機会なので今回はマークダウン記法の中でもよく使われるものをアウトプットとしてまとめておこうと思います。

環境

  • OS: Windows
  • IDE: Cloud9

READMEってなに？

READMEとは「Read(読んで) Me(私を)」という意味で、ソフトウェアプロジェクトやリポジトリに含まれるテキストファイルのことを指します。 ファイル名であるREADME.mdの.mdは、Markdown(マークダウン)の拡張子です。 そのため、READMEを書くときの記法はマークダウン記法となります。 （ここのZennの記事を書くときの記法もマークダウンですね。）

マークダウン記法とは

シンプルで読みやすいテキスト形式の書式設定方法のことです。 テキスト文書を簡単にスタイリングしたり、リンクを作成したり画像を挿入したりすることができるテキストベースの軽量なマークアップ言語の一つ。ウェブ上で広く使用されています。 では早速、よく使われる書き方をいくつか挙げていきましょう。

見出し

マークダウン記法では、行頭の#の個数がH1-H6を表します。 書き方は、#(シャープ) + 半角スペース

# H1見出し
## H2見出し
### H3見出し
 ：　　 ：

若しくは、 =(イコール行)の挿入か、-(ハイフン行)の挿入

H1見出し
==================
H2見出し
------------------

強調・斜体

*(アスタリスク)か、_(アンダースコア)で囲む より強く強調したい場合は、テキストの両サイドに2つずつ付ける

*テキスト*  *テキスト*
**テキスト**  **テキスト**

改行

行末に半角スペース2つ打つ

テキストテキスト。␣␣（← 半角スペース×2）
テキストテキスト。

段落

段落を変えたい行と行の間に一行、空行を入れる

テキストテキスト。
（空行）
テキストテキスト。

リスト

箇条書きは + - * のどれか + 半角スペース

+ テキスト
- テキスト
* テキスト

数字 + .(ドット) + 半角スペース + テキスト とすれば番号付きリストに

1. テキスト
2. テキスト

Tabかスペース4つを入れるとネストすることが可能 番号付きリストをネストすることもできる

Note ネスト(Nest)とは、ある処理の中にさらに制御文を含む入れ子構造のことを言います。 例えば、if文の条件分岐やfor文でのループの記述のようにインデントを利用して入れ子構造になっているものがそれに当たりますね。プログラムの処理の複雑さや柔軟性を高めるために利用されます。

* テキスト
    * テキスト
        * テキスト
    * テキスト
        * テキスト
+ テキスト
    1. テキスト
    2. テキスト
↓こう表示されるよ
  • テキスト
    • テキスト
      • テキスト
    • テキスト
      • テキスト
  • テキスト
    1. テキスト
    2. テキスト

テキストリンク

[] + () (ショートカットキーCtrl + Kでもリンク挿入可能)

[アンカーテキスト](リンクのURL)
ex)
[これはGoogleのリンクです。](https://www.google.co.jp)

アンカーテキストとは、リンクのクリック可能な部分（表示されるテキスト）のことを指す。

↓こう表示されるよ

ex) これはGoogleのリンクです。

画像リンク

テキストリンク挿入時のように表記し、先頭に!(エクスクラメーションマーク)をつける

![altテキスト](https://画像のURL)

Note [altテキスト]はAlternative Textと言い、画像の代替テキストを指定するための記法のことを言います。 画像リンクを挿入する際にこれを指定することで、画像が表示されなかった場合や読み込まれない状況が発生した際に代わりに表示されるテキストを指定することができます。

引用

行頭に> + 半角スペース

> これは引用文です。
> これは別の行の引用文です。
> "これは引用文です。文の途中で改行をしても
ダブルクォーテーション内は改行されません。"

引用記号を追加することで、引用内にさらに引用をつくる入れ子も可能

> これは引用文です。
>> これは2番目の引用です。
>>> これは3番目の引用です。
↓こう表示されるよ

これは引用文です。

これは2番目の引用です。

これは3番目の引用です。

👀作成中に画面での見え方を確認したい

記述時の画面と表に出る画面では見え方が異なるので、実際の画面でうまく表示されているかは上げる前に確認しておきたいところ。 Previewで確認しながら書いていくと、適用されていない箇所にすぐ気づけて修正することができます。以下に、各Previewの表示方法を紹介していきます。

GitHub上で作成、編集中の場合

記述するスペースの上にある Edit | Preview タブで画面を切り替えることが可能。 GitHub article creation screen.

AWS Cloud9の場合

HTMLファイル作成時にファイルのプレビューを見る時と同じ手順で実際の画面での見え方を確認することができます。 上部タブのPreviewからPreview File README.mdを選択 AWS Cloud9 article creation screen.

Zennの場合

READMEではないけれど、こちらのZennで記事を書く際もマークダウンで記述するので一応こちらも。 Ctrl + Pのショートカットを使うか、記事作成時に右上に出ている▶をクリックするとプレビューが見れます。 Zenn article creation screen.

最後まで読んでいただきありがとうございました。 プラスの情報や修正点等ありましたら、ご連絡いただけますと幸いです。

参考リンク

今回の記事に関連する公式ドキュメントや参考情報です。