ホエールテックのonumaroです。

お待たせしました。
お待たせしすぎたのかもしれません。
、、、、はい、どこかで聞いたことのあるフレーズで大変恐縮ですが、

前回の「その１〜README編」から、気づけばそれなりの月日が流れておりました。
「その２、まだ？」と（きっと日本のどこかで一人くらいは）思ってくださっていたであろう皆さまへ、ようやくお届けできることを嬉しく思います。

相変わらずonumaroは、丁寧で妥協のない先輩エンジニアたちに囲まれながら、
日々「もの作り」に勤しんでおります。

と、前置きはさておき、今回はいよいよ前回予告しておりました、
マークダウン記法に焦点を当てて、「読みやすくて重宝されるREADME」を自分の手で書けるようになることを目的としてお伝えできればと思います。

本記事の最後に、コピペで使用できるマークダウン記法チートシートがありますので、それだけでも是非ご活用いただければ嬉しいです！

この記事の目次

1.【問題】READMEの「型」は分かった。でも、いざ書くと崩れる問題
2.【結論】結局、覚えることは「ほんの少しの記号ルール」だけ
3.【理由】なぜ、READMEはマークダウンで書くのか
4.【具体的な方法・その１】そもそもマークダウンとは？
5.【具体的な方法・その２】マークダウンの書き方一覧
6.まとめ

1.【問題】READMEの「型」は分かった。でも、いざ書くと崩れる問題

前回の「その１〜README編」では、READMEに何を書けばいいのか、という構成（型）をご紹介しました。
プロジェクトの概要、主要技術、コマンド一覧、ディレクトリ構成、開発環境構築方法などなど、、、
「なるほど、この順番で書けばいいのか」とイメージは掴んでいただけたかと思います。

ところが、です。

いざ自分でREADME.mdを開いて書き始めると、こんな壁にぶつかった経験はないでしょうか。

・見出しを大きく目立たせたいのに、ただの # という文字がそのまま表示されてしまう
・改行したはずなのに、プレビューで見ると文章がぜんぶ繋がってしまう
・表（テーブル）を作りたいけど、書き方が分からずスクリーンショットで妥協してしまう
・リストにしたいのに、なぜかインデント（字下げ）が効かない

【誤ったマークダウン記法を記述し、結果が崩れて表示されてしまっている残念なREADMEの例】

実は、駆け出しの頃のonumaroがまさにこれでした。
「READMEに何を書くか」は分かったのに、「どう書けば意図した見た目になるのか」が分からず、その都度ネットで調べては試し、を繰り返していました。

ここでいう「どう書けば意図した見た目になるのかの書き方」こそが、
今回の主役である「マークダウン記法」です。

前回はREADMEという料理の「レシピ（何を作るか）」をお伝えしましたが、今回はそのレシピを実際に形にするための「包丁の使い方（どう書くか）」をお伝えする、そんなイメージで読んでいただけると嬉しいです。

2.【結論】結局、覚えることは「ほんの少しの記号ルール」だけ

先に結論からお伝えします。

マークダウン記法は、
「 # (半角シャープ)」 や 「 – (半角ハイフン)」 や 「 | (半角パイプ記号)」
といった、ごく身近な記号を「お約束のルール」に沿って置くだけで、文章の見た目を自動で整えてくれる記法です。

HTMLのように<h1>見出し</h1>のような
記法や属性、ボーダーボックス、コンテンツボックス、インライン要素、ブロック要素のような無数にある概念、タグまで書く必要も覚える必要もありません。

驚くべきは覚えるべき記号は片手で数えられるほどのみ。
しかも一度覚えてしまえば、READMEはもちろん、Qiita・Zenn・Backlogのコメント欄、さらには最近だとChatGPTのようなAIへの指示文まで、驚くほど幅広い場所で使い回せます。

つまり、

「ほんの少しの記号ルールを覚えるだけで、誰が読んでも分かりやすいドキュメントが、技術レベルに関係なく書けるようになる」

これが今回一番お伝えしたい結論です。

3.【理由】なぜ、READMEはマークダウンで書くのか

「見た目を整えるだけなら、HTMLでもいいのでは？」と思われるかもしれません。
ここでは、なぜREADMEではマークダウンがこれほどまでに使われているのか、その理由を（少しだけ歴史も添えて）ご説明します。

理由その１：そもそも「読みやすさ」を最優先に生まれた記法だから

マークダウンは、2004年にジョン・グルーバー（John Gruber）氏によって（アーロン・シュワルツ氏の協力のもと）作られた記法です。
その一番の設計目標は、「マークアップの記号だらけにせず、生のテキストのままでも人間が読みやすいこと」 でした。

ただHTMLは、

・見出しなら　　　　　　 =>　<h1>見出し</h1>、
・セクション分けなら　　 =>　<section>セクション</section>
・ 画像のラッパーなら　　=>　<figure>画像を囲む</figure>
・ 番号がないリストなら　=>　<ul><li>番号なしリスト</li></ul>
・ 番号があるリストなら　=>　<ol><li>番号付きリスト</li></ol>
・テーブルなら　　　　　 =>　<thead><tr><th>テーブルヘッダー</th></tr></thead>
　　　　　　　　　　　　　　 <tbody><tr><td>テーブルボディ</td></tr></tbody>
　　　　　　　　　　　　　　 <tfoot><tr><td>テーブルフッター</td></tr></tfoot>

のように役割、見た目ごとにタグで囲む必要があり、記号が増えて生の文章が読みにくくなりがちでした。

そこでマークダウンは、HTMLのような重たいタグを使わず、「#(半角シャープ)」 や「*(半角アスタリスク)」 といった 軽い記号だけで済むように設計されています。

この読みやすさこそが、20年経った今も愛され続けている理由の一つです。

理由その２：GitHubが標準として採用しているから

私たちエンジニアがREADMEを置く場所といえば、多くの場合GitHub（ソースコードを保存・共有するためのサービス）です。
そしてGitHubは、リポジトリ（プロジェクトの保管場所）を開いたとき、トップに置かれたREADME.mdを自動的にマークダウンとして解釈し、きれいに整形して表示してくれます。

理由その３：プレーンテキストなので、どこでも・軽く・壊れにくい

マークダウンは、特別なソフトがなくても、メモ帳やVimのようなただのテキストエディタで書けます。
ファイルの実体はただのプレーンテキスト（装飾情報を持たない、素の文字だけのデータ）なので、容量も軽く、どんな環境でも開けて、10年後に開いても中身が読めなくなる心配がほとんどありません。

READMEは「新しく参加した人が、まず最初に頼りにする手引き書」です。だからこそ、誰の環境でも確実に開けて、誰が見ても読みやすい——その要件にマークダウンはぴたりとハマる、というわけです。

4.【具体的な方法・その１】そもそもマークダウンとは？

ここからが本題です。まずは改めて、マークダウンの正体を一言でまとめておきましょう。

マークダウン（Markdown）とは、
「 # (半角シャープ)」や「 – (半角ハイフン)」 のような簡単な記号を使って、プレーンテキストに見出し・リスト・強調などの装飾を加えるための、軽量なマークアップ言語のこと。

そして、その装飾ルールに沿って書かれたのがREADME.mdというファイルです。
マークダウンに対応したツールが、この記号まじりのテキストを読み取って、自動できれいな見た目に整えてくれる——これが前回からの一連の流れです。

とはいうものの、言葉で説明するより、実際に手を動かして見た方が100倍わかりやすいのがマークダウンの良いところ。

というわけで、次の章で「書き方一覧」を、
「マークダウン記法（生のコード）」と「実際の表示結果（画像）」をセットにしてご紹介していきます。

5.【具体的な方法・その２】マークダウンの書き方一覧

お待たせしました。
ここからは実際の記法を、ひとつずつ見ていきます。
前半は「どこでも使える基本の記法」、
後半は「さらに便利な拡張の記法」
の二部構成でお伝えします。

【基本編】どこでも使える記法

5-1. 見出し（Heading）

文章の先頭に半角の「 # (半角シャープ)」をつけると見出しになります。

「 # (半角シャープ)」の数が増えるほど、見出しは小さくなります。

・「# (半角シャープ)」が1つ　=　h1(一番大きい見出し)
・「# (半角シャープ)」が2つ　=　h2(2番目に大きい見出し)
・「# (半角シャープ)」が5つ　=　h5(小さい見出し)

【上記の見出しの記法の表示結果】

5-2. 強調：太字と斜体（Bold / Italic）

文字を目立たせたいときに使います。「 * (アスタリスク)」で文字を囲みます。

・ **文字**（アスタリスク2つ）で太字
・ *文字*（アスタリスク1つ）で斜体
・ ***文字***（アスタリスク3つ）で太字かつ斜体

【太字・斜体の表示結果】

5-3. 箇条書きリスト（Unordered List）

順番のない項目を並べるときに使います。行の先頭に -（ハイフン）、*（アスタリスク）、+（プラス）のいずれかと半角スペースを置きます。どれを使っても結果は同じですが、READMEでは – で統一するのが読みやすくおすすめです。

行の先頭に半角スペースを入れて字下げすると、入れ子（ネスト）にできます。

– 主要技術
　- バックエンド
　　　- Laravel
　　　- MySQL
　- フロントエンド
　　　- Vue.js
– 開発ツール
　- Docker

【箇条書きリスト（入れ子あり）の表示結果】

5-4. 番号付きリスト（Ordered List）

手順など、順番のある項目を並べるときに使います。行の先頭に1. のように「数字＋ピリオド＋半角スペース」を置きます。

1. Dockerを起動する
2. コンテナに入る
3. マイグレーションを実行する

【番号付きリストの表示結果】

5-5. リンク（Link）

[表示するテキスト](リンク先のURL)の形で描きます。

角カッコ[ ]の中がクリックできる文字（アンカーテキストといいます）、丸カッコ( )の中が飛び先のURLです。 [マークダウン記法を使って、分かりやすく重宝されるREADMEを作成しよう・その１〜README編](https://www.whaletech.co.jp/blog/readme-markdown-1/)

【リンクの表示結果】

5-6. 画像（Image）

リンクの書き方の先頭に
!（エクスクラメーションマーク）をつけると画像の挿入になります。

の形です。

角カッコの中の「代替テキスト（altテキスト）」は、画像がうまく読み込めなかったときに代わりに表示される説明文です。
画面を読み上げるソフトを使う方にも内容が伝わるので、簡単でよいので入れておくと親切です。

【画像がREADMEに表示された結果】

5-7. インラインコード（Inline Code）

文章の途中で、コマンド名やファイル名、変数名などを「コードですよ」と示したいときに使います。バッククォート（キーボードの左上あたりにある記号）で文字を囲みます。

【インラインコードの表示結果】

5-8. コードブロック（Code Block）

複数行のコードやコマンドを、まとめて「コード領域」として囲みたいときに使います。
バッククォートを3つ並べた行で、コードを上下から挟みます。
最初のバッククォートの後ろに言語名（php、bash、jsonなど）を書くと、その言語に合わせて色分け（シンタックスハイライト）してくれます。

【コードブロックの表示結果】

5-9. 引用（Blockquote）

行の先頭に > をつけると、引用として、左に縦線が入った少し目立つブロックになります。参考にした文章の抜粋や、補足メモを添えるときに便利です（この記事の「補足」「ワンポイント」ボックスも、この引用記法で作っています）。

READMEはプロジェクトの手引き書です。
新しく参加した人が最初に読む場所として整えておきましょう。

【引用ブロックの表示結果】

5-10. 水平線（Horizontal Rule）

—（ハイフン3つ）だけの行を書くと、区切りの横線が引けます。READMEでセクションの切れ目をはっきりさせたいときに重宝します（この記事でも各章の区切りに使っています）。
ここまでが前半の説明です。

【水平線の表示結果】

【拡張編】さらに便利な記法

ここからは「拡張記法」と呼ばれる、基本記法にさらに便利な機能を追加したものです。
テーブルやチェックボックスなど、READMEを一段と「重宝される」レベルに引き上げてくれる、実務で本当に使う記法たちです。

【注意】ツールによっては対応していないこともこれらの拡張記法は、多くのマークダウンツールで使えますが、ツールによっては表示に対応していない場合があります。READMEを複数の場所で見せる予定があるときは、念のため表示崩れがないか確認しておくと安心です。

5-11. テーブル（Table）

前回のREADMEでも大活躍した「表」です。
|（パイプ、縦棒）で列を区切り、2行目に |—|—| のような区切り行を入れることで、1行目が見出し行になります。
区切り行のコロン : の位置で、文字寄せも指定できます（:— で左寄せ、:—: で中央寄せ、—: で右寄せ）。

【テーブルの表示結果】

5-12. 取り消し線（Strikethrough）

文字を「 ~ (チルダ)」2つで囲むと、取り消し線が引けます。

【取り消し線の表示結果】

5-13. タスクリスト（Task List / チェックボックス）

箇条書きの – の後ろに[ ]（空のカッコ）を書くとチェックボックスになり、
[x]と書くとチェック済みになります。
TODO管理や、環境構築のチェックリストとして重宝します。
※実際にチェックボックスはON/OFFします

• [x] Docker のインストール
• [x] リポジトリのクローン
• [ ] 環境変数ファイル(.env)の設定
• [ ] マイグレーションの実行

【タスクリスト（チェックボックス）の表示結果】

5-14. エスケープ（記号をそのまま表示したいとき）

「 *（アスタリスク） や #（シャープ） を、装飾ではなく、ただの文字として表示したい」というときは、
記号の直前に 「\（バックスラッシュ、Macでは option + ¥ などで入力）」をつけます。
これをエスケープといいます。
\*本番環境では実行しないでください
とすると「・」に変換されません。

【エスケープの表示結果（記号がそのまま表示される様子）】

6. まとめ

今回は以上となりますが、いかがでしたでしょうか。

前回は「その１〜README編」でREADMEの構成（何を書くか）を、
そして今回の「その２〜マークダウン記法編」でその書き方（どう書くか）を、
ひととおりご紹介しました。

この2つが揃えば、もう「分かりやすく重宝されるREADME」を、あなた自身の手で書き上げることができると思います。

改めて振り返ると、覚えることは本当にシンプルでした。


・見出しは #、リストは -、表は |、コードは ` で囲む
・段落を分けたいときは、空行を1つはさむ
・テーブルやチェックボックスといった拡張の記法を使えば、READMEをさらに分かりやすくできる


最初は記号を確認しながらの手探りで、少しだけ手間に感じるかもしれません。
でも、これは自転車の練習と同じで、数をこなせばあっという間に手が覚えます。気づけば何も見ずにスラスラ書けるようになっているはずです。

そして何より——READMEをていねいに整えるという行為は、
「後から参加してくる誰かのことを想像して、手を差し伸べること」 だとonumaroは思っています。


前回の記事で触れた「新規参入者の手引き書」という言葉には、そういう気持ちも込めています。
マークダウンは、そのやさしさを形にするための、とても心強い道具です。

まずは今日、お手元のプロジェクトに README.md を1つ追加して、# プロジェクト名 と一行だけでも書いてみてください。

その小さな一歩が、明日のあなた自身や、いつかのチームメンバーを、きっと助けてくれるはずです。


長くなりましたが、ここまでお付き合いいただき、ありがとうございました。

待った甲斐があったと思っていただけたなら、これほど嬉しいことはありません。
それでは今日はここまでです、次の「もの作り」の話でお会いしましょう。


次回は、
「マークダウン記法を活用、ディレクトリ構造を整理して、AIエージェントでハーネスエンジニアリング、ループエンジニアリングをしてみよう」
という記事を書くかも？？
　
乞うご期待！！

「マークダウン記法のチートシート」をプレゼント

以下の「コピーボタン」を押下してお好きな記法をご使用ください