Readable Markdown ～読みやすい Markdown の書き方～

はじめに

読みやすい Markdown の書き方に関するネタが意外と見当たらなかったので、自分が普段心がけている（ことがある）ことをまとめてみました。

※そのうち特に細かいネタに絞ってお届けします。

常に使う系

設定より規約というか、いろんな書き方がある中で「あえてこの書き方で固定する」的な発想。

常に見出しは # xxxx を使う

この見出しの書き方は使わない
----------------------------

理由:

• エディタ側の設定でハイライトしづらい
• - やら = を何個も書くのがしんどい（たしか最小は 2～3 個で良いんでしたっけ？）
• 見出しを grep できない、するにしても \n やら改行絡みのオプションやらが絡んできてだるい

常にリストは - を使う

* アスタリスクで書くリストは使わない

理由:

• Shift 押さないと打てなくてだるい
• 太字の **太字** とかと被って視覚的にちょっと見辛い
• はてな記法など他記法が「見出し」として * XXXX を採用していることがあり、Markdown で書いたのをそのまま貼り付けると衝突することがある

常に番号無しリスト＋手動番号を使う

1. 番号付きリストは、
1. 使わない。

理由:

• 番号の補われ方にクセがある（パーサで微妙に違ったりする）ので、いちいち「ちゃんと反映されてる？」を心配する手間が生じがち
• リストで並べた n 番目を「n番だけだと……」みたいに参照する場合に、弱い参照になる（あとからリストいじって n がずれたら意味をなさなくなる）
• エディタ上で見た時に 0. や 1. が列挙してるのが気持ち悪い（直感的に読む時に違和感がある）

代わりに、以下のように手動で番号を振る。

- (1) リスト
- (2) リスト
- (3) リスト
    - 1: リスト
    - 2: リスト
    - 3: リスト

ただしパーサによっては (1) でも番号付きリストと解釈されることがあるので注意。私は 1: をよく使う。また順序に意味がない場合は a) b) などを使うことも。

常に半角スペースで囲み、常に空行をはさむ

以下のようにする。

> 引用引用引用引用引用引用引用
> 
> 引用引用引用引用引用引用引用

引用に対するコメント

**太字** *斜体* ~~打ち消し線~~

以下のようにはしない。

> 引用引用引用引用引用引用引用
> 
> 引用引用引用引用引用引用引用
引用に対するコメント
**太字** *斜体* ~~打ち消し線~~

上記の例は少し極端だが、「空行がないせいで反映されない」「半角スペースで区切ってないせいで反映されない」ことがパーサごとにあったりなかったりするのが地味にうざいので、常に空けるように習慣化することで未然に防ぐ。

常に 4 space indent ではなく 3 backtick で整形する

整形済みテキストの表示には行頭スペース四つ or バッククォート三つ囲みがある。

    整形
       済み
           テキスト
    ↑こんな風に 4 スペースでインデントする案

｀｀｀
整形
   済み
       テキスト
↑こんな風にバッククォート(※1)で囲む案がある
｀｀｀

※表記の都合上、バッククォートを全角で書いているが実際は半角（余談だがコードブロック内でバッククォート三つエスケープするのってどうやるんだろ？）

推奨は常にバッククォートを使うこと。

インデントを使わない理由:

• raw markdown 上でコピペして使う時に先頭のインデントが邪魔
• 全行（途中の空行含む）をインデントせねばならず面倒くさい

常にテーブルはキレイに整える

以下のようにスペースを入れてキレイに整える。

| 項目 | 内容   |
| ---- | ------ |
| key1 | value1 |
| key2 | value2 |

理由:

• raw markdown 上で読みやすい
  • というか汚いテーブル表記を見た時のげんなり感を受けずに済む
• キレイに整えづらい≒表中に書く内容が冗長、なので推敲や校正のヒントになる

賛否両論激しいかもしれないが、リーダブルコードという考え方があるようにリーダブルに保つのは重要（だと個人的には思うのでキレイにする手間は惜しまない）。

全角文字については、エディタ（というかフォントか）次第ではプロポーショナルにならないので諦めるべき。ただし共有する気がない（他人が raw markdown をいじることがない）ならキレイにしても良い。

※余談だが私は Windows + 秀丸エディタ + ＭＳ ゴシックで書いているので、全角文字は半角二文字分になりキレイにしやすい。以下例。

常に画像の Alt Text は空にする＆わかりやすいファイル名を付ける

以下のように Alt Text で説明しようとしない。

![Markdownプレビュー例](image1.jpg)

理由:

• Alt Text は普段直接は見えないので、労して書く必要がない
• ファイル名が手抜きになりがちで、あとから管理しづらい

代わりに、以下のように Alt Text は最小限にしつつ、ファイル名で説明する。

![](markdown_preview_example.jpg)

アクセシビリティも考慮したいなら、Alt Text もファイル名で補う。

![markdown_preview_example](markdown_preview_example.jpg)

ファイル名は以下のように日本語でも良い。ただしパーサやシステム（特に日本語を想定してない海外製のもの）によっては上手く動作しないことがあるので注意すること。

![](Markdownプレビュー例.jpg)

![Markdownプレビュー例](Markdownプレビュー例.jpg)

見出し内パンくずリスト

以下のように子見出しは 親見出し名も包含した書き方（パンくずリスト）で書く。

※(2) Home 配下が見出し内パンくずリスト。

# (1) HERP とは
## Home
## Editable
## Reachable
## Personal
# (2) Home
## Home > ホームファイルをつくる
## Home > ゾーニングする
### Home > ゾーニングする > 二種類のゾーニング
### Home > ゾーニングする > 主なゾーン
## Home > フォーマットを設計する
### Home > フォーマットを設計する > 主な属性
### Home > フォーマットを設計する > 属性との付き合い方
### Home > フォーマットを設計する > フォーマット例
### Home > フォーマットを設計する > フォーマット設計のコツ
# Editable
……

理由:

• 目次機構を持たないシステムやエディタ上でも文書構造上の現在地を見失いにくい
  • raw markdown を書く執筆者にとっても
  • ブラウザで読む読者にとっても

現在地を見失うことについて補足する。特に本格的な長文になってくると、見出し間も広くなり、「今どの辺見てるんだっけ」といったことが起こる（現在地を見失う）。これを見出し内パンくずリストで軽減できる。

例:

• ### Home > ゾーニングする > 二種類のゾーニング
  • 「Home という観点のゾーニングについて読んでるんだな」とすぐにわかる
• ### 二種類のゾーニング
  • Home という親構造について読んでいることがわからない

この見出し内パンくずリストは プレーンテキストによるタスク管理が捗る HERP - Qiita この記事とかで使っている。

絵文字系

絵文字が使えると本当に捗る。

絵文字接頭語(Emoji Prefix)

ごちゃごちゃしがちなリストは、以下のように Emoji の接頭語(Prefix)を付けて読みやすくする。

以下はメリットとデメリットを と で見易くする例。

Markdown を書く手段の比較

- 秀丸エディタで書く
    - :o: SIer 現場でデフォなのでインストール作業不要
    - :o: 日本語完結なので導入の敷居が高く見えない
    - :x: 設定作業が設定画面ゲーで結構煩雑
    - :x: リアルタイムプレビューが使えない
- VSCode で を書く
    - :o: デフォでハイライトとプレビューがあって使いやすい
    - :o: 拡張機能でさらに使いやすくできる
    - :x: メモリ食うので貧弱環境だときつい
    - :x: 非エンジニアには導入ハードルが高い（高く見える）

以下は無秩序に並ぶ項目の各々を視覚的に読みやすくする例。

# ぼくのトリセツ

## ぼくの行動ぱたーんとか
- :keyboard: めちゃくちゃタイピングするのでうるさいです
    - キーボードショートカット多用します
    - 短期記憶がしょぼいので、いちいち外に出す必要があります
    - 普段の行動も全部リスト化して管理してるほど重度です（皆にとっての頭で考える行為 → 僕にとっては文章を書く行為になる）
- :confused: ものおぼえと暗記が壊滅的に苦手なので覚えようとしません
    - 覚えるのではなく書いて素早く読み返せるようにします
    - 短期間で大量の記憶を必要とする仕事や、短時間で大量の想起を必要とする仕事は根本的に無理なので、最初からアサインしないでください
- :neutral_face: 人と馴れ合わないので、冷たく見えるかもしれません
    - ストレングス・ファインダーの「内省」の資質が強いだけです
    - 人に興味がないわけではないです
    - ネット弁慶気味です（チャットではよく喋ります）
- :turtle: 食べるのが非常に遅いです
    - 錠剤飲むのもしんどい人間で、食道が細いので、とにかくよく噛みます
    - 不器用で、箸を使うのに慣れていない（慣れることができなかった）ので、単純に時間がかかります
    - 好き嫌いが激しいですが、栄養のために食べないといけないので、「どれとどれをどれくらいの分量で組み合わせたら食えそうか」に腐心します、その分遅いです

凡例絵文字(Explanatory Emoji)

凡例は絵文字で実現するとシンプルかつ読みやすい。

例:

# Markdown 概論
……

## 凡例
- :warning: 注意事項です
- :o: メリットを意味します
- :x: デメリットを意味します
- :memo: 可能なら押さえておきたい TIPS です
- :hammer: 工事中です

……

## リストをインデントする時のスペース数について
Markdown では 4 個単位だと定められている。

:memo: ただし 2 個単位でも動作するパーサ（あるいはビルド時のオプションとして提供）もある。他人と共有するつもりがなく、楽がしたいのなら、あえて 2 個で書くのもアリだろう。

……

絵文字会話(Emoji Conversation)

くだけた文章などで会話例や発言例を記したい場合、絵文字を使って会話している風に見せると、視覚的に読みやすい上に親しみやすさも出る。

例:

# 従業員数千人の会社に Slack を導入するまでの話
……

## 凡例
- :bug: ぼく。社内では虫のような存在である。
- :bear: 上司。見た目も口調も怖い。
- :pig: 上司の上司。態度も体（特に横幅）もでかい。

## 作戦1
- :bug: 「Slack 使いましょうよ。最近流行ってますよ。何なら啓蒙もしますよ」
- :bear: 「その工数はどこから出るん？」
- :pig: 「は？（平社員が何言ってんの？）」

ですよねー。

……

上記は（Qiita では）以下のように見える。ただの箇条書きよりも読みやすく親しみやすい（と思う）。

• 「Slack 使いましょうよ。最近流行ってますよ。何なら啓蒙もしますよ」
• 「その工数はどこから出るん？」
• 「は？（平社員が何言ってんの？）」

上記では「この絵文字はこの人を表す」的な対応（対応的絵文字会話）を定めているが、定めずにその場で記しても良い（突発的絵文字会話）。むしろ本格的にストーリーを導入した文章でもなければ、この突発的がメインにだろう。

## 想定される反論
- :dog: 「工数はどこから出るの？」
- :cat: 「メールでも仕事できてるのに苦労して変える意味は何？」
- :pig: 「クラウドに保存されるんでしょ？セキュリティダメやん」
- :cow: 「お高いんでしょう？」

突発的で書く場合、3文字の生物系絵文字を使うと打ちやすく、列も揃ってキレイなのでおすすめ。使えるのは以下。

• :dog: 犬
• :cat: 猫
• :pig: 豚
• :cow: 牛
• :ram: 羊
• :rat: 鼠
• :ant: 蟻
• :bug: 虫

ちなみに サイレントベアプログラミング にも使えたりする。

区切り系

ややくどいくらいに区切ると、視覚的に明確で読みやすくなる（ことがある）。

区切り見出し(Section As A Separator)

特に大見出しに区切り文字を書くことで、視覚的な区切り効果を強調させることができ、読みやすくなる。

例:

# ====== 第一部 =====
# 第１章
## 1-1. 
## 1-2. 
## 1-3.
……
# 第２章
……

# ====== 第二部 =====
……

区切り見出しの書き方例:

• # ======== イコールで区切る ========
• # -------- ハイフンで区切る --------
• :bow: お詫びとお願い :bow:
  • 絵文字で区切る

区切り見出しが使えそうなケース:

• 目次機構が中見出しや小見出しを認識してくれないとき
  • 例: 大、中、小 → 大(区切り見出し)、大、中にする
  • これなら小見出しを認識しない目次機構でも「小見出し（に相当する中見出し）」を表示できる
• 大中小の三階層で扱いたいのに、構造として部、章、節、項など四階層が必要な時
  • 部を区切り見出しにする

強欲な水平線(Greedy Horizon)

水平線は一行分だけだと視覚的に弱いので、区切りとして使いたいなら n 行分重ねて書くと良い。

ダメな例:

***

良い例:

***
***
***

さらに強調させたいなら(過剰すぎるかも):

***
***
***
***
***

強欲な水平線が使えるケース:

• 見出しの「視覚的な区切りの効果」が弱い場合
  • 例1: CSS などで見栄えをカスタマイズできないとき
  • 例2: ブラウザ上など raw markdown 編集時にハイライトが効かないとき
• 区切り見出しを書くのが面倒くさい場合
  • # ======== 第一章 ======== ← こういうの書くのは面倒くさい
  • 区切り見出しなら *** を打って行コピペするだけですぐ挿入できる
• 見出しとか文章構造とかどうでもいいんだよとにかく視覚的に文章を「塊」に分けたいんだよ、というとき

神ハイライト

整形済みテキストは下手に Markdown で書くよりもコードブロックで囲んでしまった方が楽な時もある。

これは多用すると「神クラス」みたく何でも抱える存在になってしまうので、注意喚起も込めて 神ハイライト と名付けられている。

神ハイライトの例を一つ示す。たとえば元々以下のような文章があったとする。これを Markdown で書きたい。どうするか。

Markdown を書く手段の比較
・秀丸エディタで書く
  ・SIer 現場でデフォなのでインストール作業不要
  ・日本語完結なので導入の敷居が高く見えない
  ・設定作業が設定画面ゲーで結構煩雑
  ・リアルタイムプレビューが使えない
・VSCode で を書く
  ・デフォでハイライトとプレビューがあって使いやすい
  ・拡張機能でさらに使いやすくできる
  ・メモリ食うので貧弱環境だときつい
  ・非エンジニアには導入ハードルが高い（高く見える）

愚直に Markdown で書いた場合(書くのがだるい):

Markdown を書く手段の比較

- 秀丸エディタで書く
    - :o: SIer 現場でデフォなのでインストール作業不要
    - :o: 日本語完結なので導入の敷居が高く見えない
    - :x: 設定作業が設定画面ゲーで結構煩雑
    - :x: リアルタイムプレビューが使えない
- VSCode で を書く
    - :o: デフォでハイライトとプレビューがあって使いやすい
    - :o: 拡張機能でさらに使いやすくできる
    - :x: メモリ食うので貧弱環境だときつい
    - :x: 非エンジニアには導入ハードルが高い（高く見える）

コードブロックでハイライトした場合(囲むだけなので楽):

｀｀｀
Markdown を書く手段の比較
・秀丸エディタで書く
  ・SIer 現場でデフォなのでインストール作業不要
  ・日本語完結なので導入の敷居が高く見えない
  ・設定作業が設定画面ゲーで結構煩雑
  ・リアルタイムプレビューが使えない
・VSCode で を書く
  ・デフォでハイライトとプレビューがあって使いやすい
  ・拡張機能でさらに使いやすくできる
  ・メモリ食うので貧弱環境だときつい
  ・非エンジニアには導入ハードルが高い（高く見える）
｀｀｀

※表記の都合上、バッククォートを全角で書いているが実際は半角

リンク系

URL やファイルパスなどリンク系の書き方にも工夫の余地が多い。

カジュアリンク(Casualink)

カジュアリンク(Casualink)とは「さりげないリンク」とも呼ばれる手法で、文章の途中で、文章に対してリンクを張るというもの。

カジュアリンクの例

……実は [英語版Googleでググるのが一番の近道](https://www.google.co.jp/webhp?hl=en) なんですけどね。……

カジュアリンクでない例

……実は英語版Googleでググるのが一番の近道なんですけどね。……

参考:

- [英語版Google](https://www.google.co.jp/webhp?hl=en)。

カジュアリンクのメリット:

• 書く人
  • 手軽かつ自然にリンクを記述できる
• 読む人
  • リンク領域が広いのでクリックしやすい
  • 視線移動が少ないので読みやすい

Direct URL

好みの問題だが、リンク記法でリンクを書くよりも Direct URL（URL を貼り付ける＋説明を併記）にした方が良い人もいる。

リンク記法

[英語版Google](https://www.google.co.jp/webhp?hl=en)

Direct URL（の一例）

- 英語版Google
  - → https://www.google.co.jp/webhp?hl=en

英語版Google: https://www.google.co.jp/webhp?hl=en

Direct URL を使う理由:

• 読む人
  • 「どのドメインに飛ぶか」が見えるので心理的に安心しやすい
    • まあ性悪説マンなら [https://www.google.co.jp/webhp?hl=en](有害サイトのURL) とかも疑うので意味ないが
  • URL という文字列の塊は視認しやすく、リンクの存在や位置の認知に要するコストが少ない
• 書く人
  • []() といった記号を打たなくて良いので書きやすい
  • 長ったらしい URL が見えるのでキレイに書こう（張るリンク数を減らそう、トップページに張ろう等）という意識が働きやすい
  • Markdown でない場所にコピペして読んでもらう場合に、Markdown を知らない人が []() を見てびっくりしないで済む

ただしシステムによっては URL に自動でリンクが張られないことがあるので注意(GitHub Pages で Jekyll Template 使った時とか)。

一行パス

ファイルパスを書く時は読者（自分含む）がコピペしやすいよう 一行にパスだけ を書く。

ダメな例:

本プロジェクトで使う作業フォルダ:

- \\XXXXXXX\YYYY\PJ-zzzz\docs\guide
- \\XXXXXXX\YYYY\PJ-zzzz\users\stakiran (成果物やツール色々置いてるので適宜使ってください)
- \\XXXXXXX\YYYY\PJ-zzzz\users\YourName (あなたの作業フォルダはここです)
- \\XXXXXXX\YYYY\PJ-zzzz\docs\progress (全員の日報や週報はここに集まっています)
- \\XXXXXXX\YYYY\PJ-zzzz\docs\tools

良い例:

本プロジェクトで使う作業フォルダ:

｀｀｀
\\XXXXXXX\YYYY\PJ-zzzz\docs\guide
\\XXXXXXX\YYYY\PJ-zzzz\users\stakiran
  成果物やツール色々置いてるので適宜使ってください
\\XXXXXXX\YYYY\PJ-zzzz\users\YourName
  あなたの作業フォルダはここです
\\XXXXXXX\YYYY\PJ-zzzz\docs\progress
  全員の日報や週報はここに集まっています
\\XXXXXXX\YYYY\PJ-zzzz\docs\tools
｀｀｀

※表記の都合上、バッククォートを全角で書いているが実際は半角

一行パスを使う理由:

• 圧倒的にコピーしやすいから
  • 行一つ分をコピーすれば済むので - ★この部分★\\XXXXXXX\YYYY\PJ-zzzz\docs\guide この部分にカーソルを合わせる作業が要らない
• コピーしたパスをそのまま貼り付けるだけで利用できるから
  • 例: Windows 派なら Win + R → Ctrl + V → Enter で開ける

おわりに

オレオレルール・ローカルルール・伝わりにくいマニアックネタもあったかもですが、参考になりましたら幸いです。

皆さんのテクニックもぜひ教えて下さい

ではまた。