【cheatsheet】Markdownとは？【使い方/書き方】

こんにちは。タクマ™ [@suwaru_blog] です。

今回、エンジニア向けのドキュメントや Web サービスでよく使われる Markdown 記法を解説します！
慣れると HTML より早く・マークアップされた文章が書けるのでオススメですよ。

【前提】Markdown の種類はいくつかあります

というツッコミが入る前に説明すると…
Markdown はいくつか種類が存在していて、ローカルルール毎で微妙に記述が異なります。

もし Markdown がうまく表示されない場合…

Markdown を使うためには？

① md ファイルを作成する

.md という拡張子でファイルを作成してください。このファイルに Markdown を記述します。
ファイル中身を表示するには色々と方法がありますが、3 つの方法を紹介します。

1. Google Chrome で HTML として表示する

Google Chrome に Markdown Preview Plus というプラグインを追加します。

2. Mac の Finder の Quick Look でプレビューできるようにする

Terminal から Markdown をプレビューできるようにするライブラリをインストールします。

brew tap phinze/homebrew-cask
brew cask install qlmarkdown

Finder で .md ファイルを選択状態にしてスペースキーを押して下さい。
プレビューが表示されるようになります。

3. Visual Studio Code などのエディターでプラグインを使う

モダンなエディターだと Markdown プラグインが提供されています。
Visual Studio Code でしたら「Markdown Preview Enhanced」がオススメです。

② Markdown アプリを使う

たとえば Boostnote は無料で使える Markdown 型のノートアプリです。
わざわざ .md ファイルを作らなくてもアプリ内で書けるので便利です。

Boostnote の詳しい使い方は以下リンクを参照してみてください。

③ Markdown が使える Web サービスを使う

オンライン上のサービスで Markdown を試してみるのもいいかと思います。

Markdown の書き方 (cheatsheet)

前置きが長くなってしまいましたが、
ここから Markdown の書き方を説明していきます。

プログラミングコード

① バッククオートを使った表現方法

バッククオート 3 つで挟むとプログラミングコードを表現できます。

```
function x() {
    console.log(x);
}
```

シンタックスハイライト

たとえばバッククオートの後に js や javascript と書けば、
そのコードは JavaScript のシンタックスハイライトがあてられます。

```js
function x() {
    console.log(x);
}
```

詳しくはドキュメントや、使っているサービスの Q&A を読んでください。

ファイルの差分を表現したいとき

```diff
- mysql -u sample2_user -p sample2_password sample2 < sample.bakcup
+ mysql -usample2_user -psample2_password sample2 < sample.bakcup
```

ファイル名やコメントなど

:ファイル名 とすればファイル名など補足情報を表示することが可能です。

```js:hoge.js
function x() {
    console.log(x);
}
```

② 空文字と TAB を使った表現方法

``` の代わりに 4 つ以上の空文字、または TAB を使ってもコード表現できます。
しかしシンタックスハイライト等が使えないのでイマイチです。

③ インラインのコードを表現する方法

1 行程度のコードであれば、バッククオートで挟むと強調表示できます。

`return x;`

見出し (h)

# h1 見出し
## h2 見出し
### h3 見出し
#### h4 見出し
##### h5 見出し
###### h6 見出し

h1 / h2 のショートハンド記法

h1

改行直後に = を 1 つ以上 つける

h1 見出し
=

h2

改行直後に - を 1 つ以上 つける

h2 見出し
-

改行 (br)

半角スペース 2 個 / 改行 2 個

引用表現 (blockquote)

> 引用文

区切り文 (hr)

以下のどれかで表現できます。

---

***

___

強調表示 (b)

Markdown の種類によっては、以下の記法の前後に半角スペースが必要です。

イタリック体 (斜体)

*斜体*
_斜体_

太字

**太字**
__太字__

箇条書き (ul)

- のあとに半角スペースを入れるとリストを表現できます。
入れ子リストを作りたい場合は半角スペース 4 つ、または TAB を挿入してください。

- item1
    - item1-1
    - item1-2
- item2
- item3

+ や * でも表現できます。

- item1
+ item2
* item3

リスト直下に文章を挿入する

リストの末尾に空文字 2 つを入れて改行してください。
文章の先頭には半角スペース、または TAB を挿入してください。

- item1(半角スペース2つ必要→)  
    リスト直下の文章
- item2
- item3

連番の箇条書き (ol)

1. item1
2. item2
3. item3

数字は指定しなくても自動的に連番になる

自分できっちり数字を入力しない方が、後からリスト修正するときラクになります。

1. item1
1. item2
1. item3

URL リンク (a)

URL を貼りたいだけのとき

<https://www.google.com/> のように <> で URL を囲むだけで OK です。

文字の中にリンクを仕込みたいとき

[Google](https://www.google.com/)

マウスオーバーで title 属性を表示したいとき

[Google](https://www.google.com/ "マウスオーバーでここの URL タイトルを表示する")

画像イメージを貼る (img)

![alt属性のテキスト](http://www.eglab.tokyo/public/images/svg/logo.svg)

![alt属性のテキスト](http://www.eglab.tokyo/public/images/svg/logo.svg "マウスオーバーでここの画像タイトルを表示する")

画像イメージの中にリンクを埋め込む

![alt属性のテキスト](http://www.eglab.tokyo/public/images/svg/logo.svg)(http://www.eglab.tokyo)

打ち消し線 (s)

文字の前後に ~~ を入れてください。
Markdown の種類によっては ~~ の前後に半角スペースが必要です。

~~打ち消し線~~

チェックボックス (checkbox)

以下のように書くとチェックボックスを作成できます。
[] の中に x を入れるとチェックが入ります。

- [] チェック1
- [] チェック2
- [x] チェック3

テーブル (table)

以下のように書くとテーブルを作成できます。

| 見出し | 見出し |
| ------ | ------ |
| 1      | あ     |
| 2      | い     |
| 3      | う     |
| 4      | え     |
| 5      | お     |

見出しの下の区切り線は --- または :-- で表現されます。
区切り線の - の数は適当でも大丈夫です。

要約・詳細 (summary / details)

要約・詳細だけは HTML と同じように記述します。
要約をクリックすると、詳細が展開表示されます。

<details>
  <summary>
    要約内容 (ここは常に表示される)
  </summary>
詳細 (ここは折りたたまれている。要約をクリックすると表示される)
</details>

その他の Markdown の記事

WordPress でブログを書くときにも Markdown はオススメです。
以下の記事でその理由を解説しています。