Zenn
🗃️

README -マークダウン記法-

2024/01/01に公開
Git
GitHub
Markdown
readme
idea

はじめに

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つを入れるとネストすることが可能
番号付きリストをネストすることもできる

ネストって？

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

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

テキストリンク

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

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

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

↓こう表示されるよ

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

画像リンク

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

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

[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ではないけれど、こちらの記事もマークダウンで記述しているのでおまけ。
Ctrl + Pのショートカットを使うか、
記事作成時に右上に出ている▶をクリックするとプレビューが見れる。
Zenn article creation screen.

最後まで読んでいただきありがとうございました。

プラスの情報や修正点等ありましたら、ご連絡いただけますと幸いです。

Discussion