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

  • このエントリーをはてなブックマークに追加
  • Pocket

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

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

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

今回紹介する Markdown の記述を使えば「おおよそ」正しく表示されるかと思います。
なんで「おおよそ」なんだ?ちゃんと教えてくれよ!

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

つまり方言や訛りが存在すると思ってください。標準語さえ抑えておけば大丈夫です。

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

  • 半角スペース漏れがないか確認する (よくある)
  • 他の記述方法なら表示できるかもしれないので試す
  • サポートされていない記述だったらあきらめる

Markdown を使うためには?

① md ファイルを作成する

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

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

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

  1. Markdown Preview Plus をインストール
  2. chrome://extensions にアクセスする
  3. Markdown Preview Plus の [詳細] をクリックする
  4. [ファイルの URL へのアクセスを許可する] を有効にする
  5. Markdown ファイルを Google Chrome にドラッグアンドドロップする
  6. プレビューが表示されます

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 ファイルを作らなくてもアプリ内で書けるので便利です。

フォルダ分け、タグ機能、拡張 CSS、テーマなど充実しているので是非おすすめです。

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

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

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

Markdown の書き方 (cheatsheet)

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

プログラミングコード

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

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

```
function x() {
    console.log(x);
}
```
シンタックスハイライト

シンタックスハイライト対応していない Markdown もあるので注意してください。

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

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

大体、プログラミング言語名を小文字で書くか、
プログラミング言語のファイル拡張子でシンタックスハイライトがあたります。

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

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

バッククォートの後に diff としてあげて、
+ のあとに半角スペースで、行が追加されたこと、
- のあとに半角スペースで、行が削除されたことが表現できます。

```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)

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

  • ハイフン 3 つ以上
    • h2 のショートハンド記法と認識されないように、前後に改行を入れる必要がある
  • アスタリスク 3 つ以上
  • アンダーバー 3 つ以上
---

***

___

強調表示 (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 と同じように記述します。
要約をクリックすると、詳細が展開表示されます。

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

その他の Markdown の記事

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

お仕事ください!

僕が代表を務める 株式会社 EeeeG では Web 制作・システム開発・マーケティング相談を行っています。
なにかお困りごとがあれば、Twitter DM や Web サイトからお気軽にご相談ください。

コメント

コメントを残す

*