Markdownの書き方と方言

皆さん、こんにちは。技術開発グループのn-ozawanです。
日本のモグラは、富士山を境にアズマモグラとコウベモグラの２大勢力に分かれ、数万年にも及ぶ勢力争いが繰り広げられています。

本題です。
ここ数年で、設計書や仕様書、構築手順書など、幅広くMarkdownが利用されるようになりました。しかし、中にはMarkdownを知らない、もしくは、聞いたことあるけどどういうものか分からない、という人も一定数いるのではないでしょうか。今回はそんなMarkdownの初心者向けに、その書き方などをお話しします。

Markdown

Markdownとは？

Markdownとは、プレーンテキストからHTMLへ変換するツールです。Markdownの構文でプレーンテキストを記述することで、HTMLへ変換することが出来ます。

HTMLはWEBページを記述するのに非常に有用なツールではありますが、その記述には一定のスキルが必要であり、記述されたHTML文書は編集の難しさや読み辛さがあります。Markdownは構文を出来るだけ読みやすく、編集しやすくすることを目標としています。

<p>これは段落です<p>
<ul>
  <li>リストその１</li>
  <li>リストその２</li>
  <li>リストその３</li>
</ul>

これは段落です。

- リストその１
- リストその２
- リストその３

上記はHTML(上)とMarkdown(下)の違いです。内容は同じですが、タグの記述を省略するだけで、見やすさと編集のしやすさが良くなっていることが分かります。Markdownはその記述のし易さから、設計書や仕様書などで採用しているプロジェクトが多くなっています。

以降からはMarkdownの構文についてお話しします。

段落と改行

段落は空行により分けられます。改行したいときは行末に２つのスペースを挿入します。以下の例では、分かりやすくするため、スペースを␣と表現しています。

これは段落です。
これは改行されません。

これは別の段落です。␣␣
これは改行されます。

上記をHTMLに変換すると以下のようになります。

<p>これは段落です。これは改行されません。</p>
<p>これは別の段落です。<br/>これは改行されます。</p>

見出し

行頭に#を置くことで見出しを表現することが出来ます。#の数により、見出しのレベルが変わります。

# 見出し１
## 見出し２
### 見出し３
#### 見出し４
##### 見出し５
###### 見出し６

ブロック引用符

行頭に>を置くことで引用することが出来ます。

> これは引用文です。
> 複数行にかけて記述することが出来ますが、表示する際は改行されないことに注意が必要です。
> 改行する場合は、行末に２つのスペースを挿入してください。  
>
> > ネストすることも出来ます。

リスト

行頭に*、+、-のいづれかを置くことで箇条書きにすることが出来ます。

* 赤
* 緑
* 青

+ 赤
+ 緑
+ 青

- 赤
- 緑
- 青

行頭に1. を置くことで順序付きリストにすることが出来ます。

1. 赤
1. 緑
1. 青

コード

バッククオート(`)で囲むことでインラインコードを記述することが出来ます。

これは`インラインコード`です。

行頭にタブもしくは４つ以上のスペースを置くことでコードブロックを記述することが出来ます。

    これはコードブロックです。
    行末に２つのスペースを挿入しなくても、改行することも出来ます。

リンク

リンクのテキストを[と]で囲み、リンク先のパスを(と)で囲むことでリンクにすることが出来ます。

[リンクのテキスト](http://google.com/)

また、リンク先のパスが何回も出てくる場合は、参照リンクとして定義しておくことも出来ます。

[リンクのテキスト][Google]

[Google]: http://google.com/

画像

リンクの行頭に!を置くことで画像表示になります。

![Alt text](/img/example.png)

強調

*もしくは_で囲むと強調表示されます。

*強調* もしくは _強調_ で強調して表示されます。一般的には斜体で表示されます。

**強調 もしくは __強調__ だとより強く強調されます。一般的には太字で表示されます。

Markdownの方言

先ほど挙げた書き方は、公式サイトの構文に記載されている書き方です。MarkdownはGitHubやGitLab、Stack OverflowやQiitaなどの投稿サイト、wikiなどでも活用されており、それぞれで独自の記法が方言のように存在します。以下にその一部を紹介します。

改行

行末に２つのスペースの代わりに、\を挿入することで改行することが出来ます。

これは段落です。
これは改行されません。

これは別の段落です。\
これは改行されます。

コードブロック

先ほど、「コードブロックを記述する場合は、タブもしくは４つ以上のスペースを行頭に置きます。」とありましたが、GitHubやGitLabなどの多くでは以下のように記述することが出来ます。

```
これはコードブロックです。
行末に２つのスペースを挿入しなくても、改行することも出来ます。
```

また、```の後に言語を指定することにより、コードをハイライトすることが出来ます。

```javascript
(() => {
  'use strict';

  console.log('Hello world');
})();
```

テーブル

以下のようにテーブルを記述することが出来ます。

| ヘッダ１ | ヘッダ２ | ヘッダ３ |
| --- | --- | --- |
| セル１ | セル２ |  セル３ |
| セル４ | セル５ |  セル６ |

おわりに

Markdownの利点は先にも述べた通り、見やすさと編集のしやすさにあります。また、プレーンテキストの利点として、Gitなどのバージョン管理が容易になることが挙げられます。WordやExcelなどのバイナリファイルでは、差分の確認やマージ作業が困難です。一方でプレーンテキストであるMarkdownはソースコードと同じ要領で差分の確認やマージ作業が行えます。

そういった背景からMarkdownは広く使われるようになりましたが、方言により、サイトによっては意味をなさない記法があったりします。今回投稿するにあたり初めてMarkdownの公式サイトを見たのですが、これ方言だったんだ！という新しい発見がありました。Markdownを活用する際は方言を理解しつつ利用した方が良いですね。

ではまた。