Posted at

細かすぎて伝わらない俺俺 Markdown 書き方ルール

More than 1 year has passed since last update.

※チームや利用サービスなどシチュエーション次第では鳴りを潜めることもある。


見出しは # で書く

以下を使う。

# タイトル

以下は使わない。

タイトル

========

使わない理由は「エディタによってはシンタックスハイライトできない」「書くのがだるい」から。

え?大見出しを視覚的に認識しづらい?シンタックスハイライトされてればそんなことはないはず(まあ plain でも見易く、という Markdown のコンセプトからは外れてしまうが)。


前後にスペースを設ける

以下を使う。

これは **太字** です。

以下は使わない。

これは**太字**です。

使わない理由は「実装によっては正しく認識されないことがある」「検索やパースがし辛い(スペースがあるとスペースも目印にできるのでちょっと楽できる」から。


URL の前後にもスペースを設ける

以下を使う。

ソースは https://www.example.com/ です。

以下は使わない。

ソースはhttps://www.example.com/です。

使わない理由は「実装によっては正しく認識されないことがある」「エディタによっては正しくハイライト or クリッカブルリンク化されないことがある」から。


前後に空行を設ける

以下を使う。

引用します。

>引用です
>引用です
>引用です

引用しました。

以下は使わない。

引用します。

>引用です
>引用です
>引用です
引用しました。

使わない理由は「正しく認識されない」から。


太字や斜体で _ を使わない

以下を使う。


  • *斜体*

  • **太字**

以下は使わない。


  • _斜体_

  • __太字__

使わない理由は「_ は変数名やファイル名など普通に識別子としても使うものであり記法として使うのは違う」と思うから。this_is_a_snake_case こんなのも斜体で強調されてしまうため辛い(GitHub は上手いこと回避しているようだが)。


斜体は使わない

文字の強調は 太字 や「かっこ」で良いと思うから。斜体は要らない子。

(でも本格的なドキュメントや英語テキストだとそうもいなかったりする)


リストは - で書く

以下を使う。

- リスト

- サブリスト
- サブサブリスト

以下は使わない。

* リスト

* サブリスト
* サブサブリスト

使わない理由は「打ちづらい(Shiftキーが必要)」「他の記法にコピペした時に見出しになっちゃう(例: Pukiwiki やはてな記法)」から。


リストのインデントはスペース2つ

以下を使う。

- リスト

- サブリスト
- サブサブリスト

以下は使わない。

- リスト

- サブリスト
- サブサブリスト

使わない理由は「4つもスペース打つのだるい」「あっスペース1個足らん、みたいな打ち間違いが起きやすい(距離感がわかりづらい)」から。

ただし実装(Qiita含む)によっては4スペースでないと正しく認識されない(特にサブサブ以降)ことがあるので、その時は諦めて4スペース。


順序付きリストは使わない

以下は使わない。

- 1. まず hogehoge します

- 2. 次に fugafuga します
- 3. 最後に piyopiyo します

理由は「数字の表記が実装によって異なる(たとえば GitHub だと i. ii. iii. のようになる)」から。

じゃあどうするかというと、面倒くさいが順序無しリスト + 番号も自分で書く。以下に例を示す。

- (1) まず hogehoge します

- (2) 次に fugafuga します
- (3) 最後に piyopiyo します

これなら望みの表記で列挙できる。

え?番号が5とか10とか20になったら面倒くさい?そこは頑張って。あるいはそもそも「本当に順序付きリストで書く必要があるのか」を考え直す。たいていは順序無しリスト(+αで「以下の順に実行してください」的な付記を付ける)で事足りる。


Ascii Art を書く時は日本語を使わない

以下を使う。

モジュール相関図

+---------[Module-B] 備考
|
|
[Module-A] 備考
| 備考
|
+---------[Module-C] 備考

以下は使わない。

モジュール相関図

+---------[モジュールB] 備考
|
|
[モジュールA] 備考
| 備考
|
+---------[モジュールC] 備考

使わない理由は「日本語の表示幅は実装依存(あとは見ている側のブラウザ設定依存)でありズレやすい」から。


引用はコードハイライトで書く

以下を使う(※注: Qiitaではコードハイライト表記中で backtick をエスケープできないっぽいので backtick の代わりに ' で書いている)。

'''

引用です

引用です
'''

以下は使わない。

> 引用です

>
> 引用です

使わない理由は「各行に > を書くのがだるい」から。


横に伸びるのがイヤなら引用は引用表記で書く

ただしコードハイライト表記は(一行が長い場合)ウィンドウ端でも改行されずに横に伸びるので、それがイヤなら引用表記を使う。

ハイライトした例:

loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooongline

引用表記した例:


loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooongline



GFM はバリバリ使う

絵文字 :smile: ( :smile: )とか。



  • タスクリスト (- [] タスクリスト) とか。

打ち消し線 (~~打ち消し線~~) とか。

これらは Markdown ではなく GFM(GitHub Flavored Markdown) の文法だが、GFM は遠慮なく使って良い。GFM は Markdown のデファクトスタンダードだと思ってるんで。それに「ぼく GitHub 使ってますよ」のアピールにもなる(レガシーな会社では同類を見つけるために地味に重要)。