今更聞けない Markdown の書き方 & 環境整備（with VSCode）

こんにちは。
開発チームのワイルド担当、まんだいです。

Markdown という文書フォーマットをご存知の方は多数おられると思いますし、常用されている方も多いと思います。
今回は、 Markdown をもっと社内に浸透させるために、必要最低限な書き方と、より strict で美しい Markdown を書くためのポイントをまとめてみたいと思います。

Markdown を使うメリット

まず、 Markdown を使った場合のメリットを考えてみます。

特に技術方面で Markdown を使うメリットは計り知れません。
Markdown は、キッチリしたフォーマットが存在するため、以下のようなことがメリットがあります。

1. 文章構造が簡単なため、他のフォーマットに変換することが容易
2. 文書を簡単な記号とルールで簡素化できるため、ドキュメントの推敲にフォーカスできる
3. Markdown 文書内にコードをソースコードを埋め込むことができる（実行できるわけではない）。特に技術方面では、文章とそれを補完するコードのパートという構成を作りやすい
4. 単なる文書フォーマットのため、特定のエディタに依存することなく文章が書ける

私が書いているビヨンドブログは、ドキュメントを書く時は Markdown で書いています（この記事も例に漏れません）。
書いた後、推敲と校正をした後、 HTML へ変換し、画像の添付やレイアウトの微調整をする、といった手順で作成しています。

変換周りは、 gulp で整備していて、 Node.js のモジュールで一発変換が可能です。
私の場合は、 CSS の制約もあって モジュールから出力された HTML はそのまま利用できないため、 自前のコンバーターを通してからモジュールで変換しています。
このように、文章構造が簡単なことで、加工がしやすいという点と、推敲にフォーカスできる点を最大限に活かしていると言えます。

またビヨンドブログで書く記事は基本的に技術寄りの記事が多いため、記事内にソースコードが書ける点も大変助かっています。

 

始めてみよう！

まずは Markdown を書き始めてみましょう。
作文を書くとき、一番右に書くのはタイトルですよね。

ですので、タイトルを書く方法を覚えてみましょう。

# 今更ですが、Markdownについてまとめてみます

 

これだけです。
今現在書いているこの記事も Markdown の時点では同じ様になっています。
word で書類のタイトルを付ける場合、タイトルをセンタリングするのか、何文字マージンを入れるのか、都度悩む必要がありますが、 Markdown なら、そういった悩みから一気に開放されます。

タイトルが書けたら、次は内容を書いていきますよね。
こんな風に書いていきましょう！

# 今更ですが、Markdownについてまとめてみます

こんにちは。
開発チームのワイルド担当、まんだいです。

Markdown という文書フォーマットをご存知の方は多数いると思いますし、常用されている方も多いと思います。

 

タイトルの後に、1つ改行を入れた後、文章を書き始めます。

なんとなく流れが分かってきたでしょうか？
後は気の向くまま、文章を書きなぐればいいんです！

 

中黒が行頭に付いたリストが書きたい

リストは HTML タグでいうところの ul タグのことという認識で OK です。

行頭に中黒が付いたリスト (unordered list) を定義するのはとても簡単です。

行頭に「-」「+」「*」のいずれかを置いて、半角スペースを1つ入力する。それだけです。

- Markdown でリストを書くのは簡単です
- 例えば、こんな風に、行頭に「-」と半角スペースを入力するだけ
  - リストのネストも行頭のスペースやタブを入れるだけでできます
- とても簡単ですね

 

気をつけることは2つあって、

• リストとリストの間に改行を入れないこと
• ネストする場合のスペース数（もしくはタブ）は色々方言がある

これだけです。

ネスト時のスペースは、エディタによって認識が違います。
この方言については、後述しますが、今の段階ではそういうものが存在するんだという程度で結構です。
エディタなら調整が効くはずなので github や backlog など、 Markdown を投稿する可能性のあるウェブサービスに合わせるよう調整できます。

 

番号付きリストが書きたい

この項目で説明する機能は HTML で言うところの ol タグに対応しています。

Markdown を使うメリットの項目で出てきた番号付きリスト (ordered list) の使い方も簡単です。
こちらの箇所の Markdown 時点のものが以下のようになっています。

1. 文章構造が簡単なため、他のフォーマットに変換することが容易
1. 文書を簡単な記号とルールで簡素化できるため、ドキュメントの推敲にフォーカスできる
1. Markdown 文書内にコードをソースコードを埋め込むことができる（実行できるわけではない）。特に技術方面では、文章とそれを補完するコードのパートという構成を作りやすい
1. 単なる文書フォーマットのため、特定のエディタに依存することなく文章が書ける

 

「1. 」という文字列が出現したら、番号付きリストが始まる合図です。
連続した番号が続く場合でも、文字列の先頭は「1. 」とします。
1がカウントアップしていっても仕様上問題ないのですが、カウントアップすると順序の入れ替えが発生した場合に数字を書き換える必要があり、メンテナンスの手間が掛かります。

こちらも気をつけることは2つだけで、リストとリストの間に改行を入れないことと、ネスト時のスペースの数だけです。

HTML のリスト表示は li タグでラップする必要があるので Markdown の方が手軽に書けますね。

 

見出しを書きたい

ある程度文量が多くなってくると、文章を章立てて書くことになります。

項目ごとに見出しを付ける方法もとても簡単で、以下のように書きます。

# 大項目（タイトル）です

ここには書き出しを書きます

## 中項目です

ここには中項目について書きます

### 小項目です

ここには小項目について書きます

 

「#」の数を増やしていけば、より小さい項目を定義することができるため、見通しが良い文章が簡単に書けそうですね。

 

リンクを定義したい

文章中にインターネット上の記事へのリンクを書きたい場合ももちろんありますよね。

そんな時も、 Markdown なら簡単に書くことができます。

[ビヨンドのコーポレートサイト](https://beyondjapan.com)へのリンクになります。

 

「[]」の中にリンクにしたい文字列を入力し、続いて「()」の中にリンク先の URL を入力します。
HTML の a タグのような使い方なので、理解しやすいでしょう。

 

ソースコードを書きたい

HTML でいうところの code タグのようなものが Markdown にも用意されています。
Markdown では、 fenced code block といいます。

```php
<?php

class hogehoge
{
    function echo($message)
    {
        echo $message;
    }
}

$a = new hogehoge();
$a->echo();
```

 

何の存在価値もないコードですが、 Markdown でソースコードを書きたい時は「`」を3つ並べた次の行から、再度「`」を3つ並べた箇所までがソースコードと認識されます。
先に出てくる「`」の後に php と書いてあるのはソースコードのプログラミング言語で、必須ではありません。

また、個数を調整することでネストすることができます。

`の代替文字として~（チルダ）も利用可能ですが、混ぜて使うことはできません。

なお、本来 Markdown では、 バッククォートやチルダではなく、スペース4つを fenced code block の境界線と定められていますが、一見何もないように見えますし、ビューアーによっては反応しないという認知度の低さなので、薀蓄程度に覚えておけば、ひけらかせる場面もあるでしょう。

 

テーブルを定義したい

絵面的に一番派手なのが、テーブルかなと思います。

書き方としては、以下のような形になります。

Column A | Column B | Column C
---------|----------|---------
 A1 | B1 | C1
 A2 | B2 | C2
 A3 | B3 | C3

 

見た感じテーブルのように見えなくもないですが、ビューアーが「|」の数に応じてきれいに体裁を整えてくれるため、非常に便利です。
要素が横一列に並んでいるため、行単位での入れ替えが非常に便利なのはポイントが高いですね。

「---------|----------|---------」の部分がヘッダ部分とデータ部分を分けているのですが、 github などはハイフンが3つ以上存在している必要があります。
VSCode では1つでもビューアーは反応してくれます。

基本的にはエディタの方が柔軟に解釈してくれるのですが、3つ程度を目安に入力するという風に考えていればよいかと思います。

 

文字の強調を定義したい

文字を強調したい場合は、「__」で強調したい文字列を囲んでやると強調表示になります。

Markdown では、このように __強調__ します。

 

スペースの位置に注意してください。
始まる時は、スペース1つ、アンダースコア2つで始めます。
終了する時は、アンダースコア2つ、スペース1つで終わります。

代替文字として「**」もあります。
どちらでも Markdown 的な定義の差異はありません。

 

方言について

文中に何度か Markdown には方言があることを匂わせる（もしくはズバリの）表現がありました。

例えば、 Markdown の拡張で一番有名なのは GitHub Flavored Markdownかなと思いますが、他にも R Markdown や Maruku 、 PHP Markdown Extra など色々な拡張方言があります。

GitHub Flavored Markdown は、アンダースコアでの強調表示が無効になっていたり、文中の URL をビューアーがリンクに変換するなどがあります。絵文字の使用も実は Markdown の仕様に含まれていません。

R Markdown は R 構文をソースコードとして書くと、パーサーが R として実行する目玉機能があります。

PHP Markdown Extra は、 HTML への変換に重きを置いているようで、 ID や class といったものを付与することができたり、 HTML と Markdown が混在するケース、ブロック要素やインライン要素といった HTML 寄りの考え方でパーサーが動くようになっています。

また、源流となったオリジナルの Markdown のことは、特に CommonMark と呼ばれていますが、そこまではテスト範囲ではない気がします。
CommonMark に関しては、かなり詳しくテストケースが HTML 化されているため、英語のページですが読んでいるだけで色んな気付きがあります。

CommonMark Spec （この記事では0.28を参考にしています）

 

Visual Studio Code で Markdown を書く場合

Visual Studio Code（以下、VSCode）で Markdown を書く場合に便利な拡張機能があるので、最後にご紹介します。
ちなみに、 VSCode で Markdown を書くと、 fenced code block 内のプログラミング言語もしっかりハイライトを効かせてくれる誰得な機能がデフォルトで付いています。

 

Markdown All in One

名前の通り、 Markdown に必要な機能が All in One になっている拡張機能です。
これさえ入れておけば、概ね快適に Markdown を書くことができます。

特に私の場合は、アイデアをリストで箇条書きにした後、体裁を整えることが多いため、エンターキーでリストを補完してくれたり、リスト上でタブキーを押せば、サブリストとなるようにタブを行頭に付けてくれたりするため、余計なキーボード操作を省いてくれる機能が最高すぎます。

Markdown All in One - Visual Studio Marketplace

 

Markdown Preview Mermaid Support

mermaid というライブラリを Markdown のプレビューでレンダリングするための拡張機能です。
mermaid はフローチャート、シーケンス図、ガントチャートを表示するためのライブラリで、 mermaid 記法を別途覚える必要はありますが、 Markdown だけで図を書けるようになるため、資料作りが捗ること間違いなしの拡張機能です。

Markdown Preview Mermaid Support - Visual Studio Marketplace

 

markdownlint

むしろ導入すると、初めの方は苦労することが多いですが、 Markdown 養成ギプスのようなものです。
かなり strict な Markdown 記法を要求され、誤った記述をした場合は、即警告が表示されます。

苦痛でしかない、というのが導入当初の記憶ですが、今では存在を忘れてすらいるくらいバッチリ矯正されました。

この拡張機能と出会って、私のMD力がかなり上がったといっても過言ではないと思います。

少なくとも、こんな記事が書ける程度には上達しました。

markdownlint - Visual Studio Marketplace

 

まとめ

Markdown 自体が HTML に変換可能な表現が出発点なので、 HTML 変換するとこうだよ、みたいな説明になってしまいましたがいかがだったでしょうか？
実は Markdown にはもっともっと色んな表現があるのですが、今回は基本的な記法に的を絞ってお届けしました。

VSCode だけになりましたが、もっと Markdown が書きやすくなるお助けツールもご紹介できたので、今回は満足しております。
markdownlint だけは、用法用量を守ってご利用いただければと思います。

あまりに辛すぎて Markdown が嫌いになってしまっては本末転倒ですので。

MD力が上がったら、議事録など速さを求められる場面でも威力を発揮してくれると思いますし、うまく仕上がった Markdown は純粋に美しささえ感じます（これこそ本末転倒の極み......!!）。

以上です。