突然ですが、マークダウン（Markdown） ってちゃんと書けていますか？
README、プルリクエスト、社内Wiki、技術ブログ……
エンジニアの仕事って、
実は コードを書くのと同じくらい「ドキュメントを書く」場面が多い んですよね。
でも安心してください。マークダウンは覚えることが少ないのが最大の魅力です。
今回ご紹介する 10個の記法さえ押さえれば、現場で困ることはまずありません。
初心者の方はもちろん、「なんとなく使ってるけど自信がない」という現役エンジニアの方にも、きっと発見があるはずです。
それでは、さっそくいきましょう！
① 見出し（Heading）
見出しは # の数でレベルを表します。
# h1 見出し（大見出し）
## h2 見出し（中見出し）
### h3 見出し（小見出し）
#### h4 見出し
＋αのコツ： # のあとには必ず 半角スペースを1つ 入れましょう。スペースがないとパーサーによっては見出しとして認識されません。現場でよく見かけるミスの堂々第1位です。また、h1 はドキュメントに 1つだけ にしておくと、構造が整って読みやすくなります。
② 太字・斜体（Emphasis）
**これは太字（ボールド）です**
*これは斜体（イタリック）です*
***これは太字かつ斜体です***
＋αのコツ： 日本語の文章では斜体がフォントによってほとんど見分けがつかないことがあります。日本語メインのドキュメントでは 太字を中心に使う のが実用的です。また、強調のしすぎは逆に読みにくくなるので、1段落に1〜2箇所くらいを目安にするのがおすすめです。
③ 箇条書きリスト（Unordered List）
- りんご
- みかん
- 温州みかん
- デコポン
- ぶどう
＋αのコツ： -、*、+ のどれでも箇条書きになりますが、チームで 記号を統一 しておくとソースの見た目が揃います。ネスト（入れ子）にするときは 半角スペース2つ でインデントしましょう。タブ文字だとツールによって崩れることがあるので、スペース派が安全です。
④ 番号付きリスト（Ordered List）
1. 企画
2. 設計
3. 実装
4. テスト
5. リリース
＋αのコツ： 実はすべて 1. と書いても、レンダリング時に自動で連番になります。途中で項目を挿入したり並べ替えたりするときに、番号を振り直さなくて済むので覚えておくと地味に便利です。ただし、ソースの可読性を考えるとちゃんと番号を振っておく方が親切な場合もあります。チームの方針に合わせましょう。
⑤ インラインコード（Inline Code）
変数 `userName` に値を代入してください。
＋αのコツ： 文章中に変数名・コマンド名・ファイル名が出てきたら、迷わずバッククォートで囲みましょう。これだけで 可読性が格段に上がります。 レビューのときにも「この人、丁寧に書くな」と思ってもらえますよ。地味ですが、信頼を積み上げる第一歩です。
⑥ コードブロック（Code Block）
const greet = (name) => {console.log(Hello, ${name}!);};
＋αのコツ： バッククォート3つのあとに 言語名を指定する と、シンタックスハイライトが効きます。javascript、python、bash、json、sql など対応言語は豊富です。「言語名なしのコードブロック」は今日で卒業しましょう！それだけでドキュメントの見栄えがワンランク上がります。
⑦ リンク（Link）
[Google](https://www.google.com)
[プロジェクトのREADME](./README.md)
＋αのコツ： よくある間違いが カッコの種類を逆にする ことです。覚え方は「角カッコ [] にテキスト → 丸カッコ () にURL」。つまり 表示テキストが先、URLがあと です。相対パスも使えるので、リポジトリ内のファイルへのリンクにも活用しましょう。
⑧ 画像（Image）
＋αのコツ： リンク記法の先頭に ! をつけるだけで画像になります。ここで大切なのが altテキスト（代替テキスト）を省略しないこと。 アクセシビリティの観点はもちろん、画像が表示されなかったときに「何の画像か」が分かる説明を入れるのは、チーム開発におけるマナーです。レビュアーにも喜ばれます。
⑨ 引用（Blockquote）
> これは引用文です。
> 仕様書の原文やSlackのやり取りを貼るときに便利です。
>
> 空行を入れれば段落を分けることもできます。
>> 引用のネスト（入れ子）もできます。
＋αのコツ： プルリクエストで「元の仕様はこう書かれていました」と根拠を示すときに特に重宝します。>> で 引用のネスト もできるので、議論の流れを整理したいときに使ってみてください。エビデンスを添えるだけで、レビューの説得力がまるで違います。
⑩ テーブル（Table）
# マークアップ・組版言語の比較
| 項目 | 説明 | 特徴・用途 |
| ---------- | --------------------------------- | ------------------------------------------- |
| Markdown | 軽量マークアップ言語 | シンプルで書きやすく、メモやREADMEに適している |
| HTML | Webページ作成用マークアップ言語 | 表現力が高く、Webサイト制作に使用される |
| LaTeX | 文書を美しく組版するためのシステム | 数式や論文作成に強く、学術用途で広く利用される |
＋αのコツ： 正直に言います。テーブルの手書きは かなり面倒 です。現場のエンジニアは「Markdown Table Generator」などのWebツールで生成してからソースに貼り付けるのが定番です。パイプ | の位置は揃えなくてもレンダリングには影響しませんが、揃えておくとソースコードの可読性がぐっと上がります。
おまけ：水平線（Horizontal Rule）
---
ハイフン3つ以上で水平線が引けます。
セクションの区切りに便利ですが、前後に空行を入れる ことを忘れないでください。
空行がないと直前の行が見出しとして解釈されてしまうことがあります。
さいごに
いかがでしたか？マークダウンの基本は、突き詰めれば今回の 10個（＋おまけ1個） に集約されます。
私がいろんな現場を経験して感じたのは、
「ドキュメントが丁寧なエンジニアは、コードも丁寧」 ということです。
マークダウンをきちんと書ける人は、それだけでチームからの信頼を得やすくなります。
最初から完璧を目指す必要はありません。
迷ったらとりあえず書いて、プレビューで確認する。
この繰り返しで自然と手に馴染んできます。
この記事が、
みなさんのドキュメントライフを少しでも快適にするきっかけになれば嬉しいです。
コツコツが勝つコツです！！