Markdownファイルを構文チェックする仕組み

コードを書きながらたくさんのドキュメントを記述する日々だと思います。その際、ちゃんとしたマークダウン記法を利用できているでしょうか？

ちゃんとしたマークダウンをかくことで、

- 書き手によらす統一したドキュメント形式を保てる
- ビューに影響を当てるようなバグを減らせる

ことが可能となります。

今回はマークダウンで記述されたファイルの品質を維持する方法に関する記事です。

静的に構文チェックを行うことを通じて、ストイックなマークダウンファイルを書けるようになります。

ここまでやる必要があるかとか諸々の事情は置いておいて、導入方法とそれに必要な情報を述べます。

以下のパッケージを利用します。


[DavidAnson/markdownlint](https://github.com/DavidAnson/markdownlint)
[igorshubovych/markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli)

# 構文エラー例

例えば

```
# Some text

## Some text
```

のように記述されている場合は、**Multiple headers with the same content**という項目に引っかかります。複数のヘッダーに対して同じタイトルが付いているとエラーが出るという、**MD024**のルールに反するためです。

マークダウンファイルの静的解析に際してどういうルールが適用されるかというと、`markdownlint`パッケージの[Rulesのページにある一覧](https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md)よりから確認することが可能です。



以下、導入方法の手順に移ります。

# 導入手順

## 必要なパッケージのインストール

以下のコマンドでインストールしましょう。



```
// npmを利用する場合

$ npm install markdownlint markdownlint-cli --save-dev

// yarnを利用する場合

$ yarn add markdownlint markdownlint-cli
```


## 実行方法

実行は簡単で、以下のコマンドで実行できます。

```
$ ./node_modules/.bin/markdownlint <対象となるmdファイル>
```

コマンドのオプションについては以下のようなオプションがあります。

```
   -h, --help                          output usage information

   -V, --version                       output the version number

   -c, --config [configFile]           configuration file

   -i, --ignore [file|directory|glob]  files to ignore/exclude
```



## ルールの設定

さて、markdownの構文に関するルールの設定の仕方ですが、ルートに `.markdownlint.json` を置くことで可能となります。

```json:.markdownlint.json
{
  "whitespace": false
}
```

こちらのファイルの記述の仕方に関しては、例えば上記のファイルのような場合は、`.md`ファイル中にスペースがあっても、見逃されるようになります。

keyの種類については

<https://github.com/DavidAnson/markdownlint#tags>

より、確認することが可能です。

# さらに便利に

みなさんがどのようなエディタ、IDEを利用しているかはわかりませんが、VSCodeを利用してるのであれば、[markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)は、markdownlintによるチェックを強く感じることができる方法の一つです。

既存のファイルに適用すると以下のように、たくさんエラーがでるでしょう。

<img width="653" alt="スクリーンショット 2018-03-01 0.24.34.png" src="https://qiita-image-store.s3.amazonaws.com/0/88357/87e4e569-e82c-1581-5fe8-fefd037ec2f4.png">

# サンプル

以下のような .mdファイルがあったとします。どういうエラーがでるでしょうか？

```
## Hoge
![2017-08-22 0 54 31](https://hogehogesample.com/sample.png)
- hoge1
- hoge2

## Hoge2
|hoge1|hoge2|
|---|---|---|
|hoge <br> hoge| hogehoge|
|hoge <br> hoge| hogehoge|
```

## 指摘される内容

VSCodeでみると以下のようにエラーが出ます。

<img width="735" alt="スクリーンショット 2018-03-01 0.40.56.png" src="https://qiita-image-store.s3.amazonaws.com/0/88357/fc28e2cd-2085-859b-9326-480c4be5f0f0.png">


## 指摘内容に沿って直してみる

直してみましょう。

```
# 何らかのタイトル

## Hoge

![2017-08-22 0 54 31](https://hoge.com/sample.png)

- hoge1
- hoge2

## Hoge2

|hoge1|hoge2|
|---|---|---|
|hoge hoge| hogehoge|
|hoge hoge| hogehoge|

```

これだとエラーが出ませんが、一つ問題があります。以下の部分、よく見てみると `<br>` が消えています。

```
|hoge1|hoge2|
|---|---|---|
|hoge hoge| hogehoge|
|hoge hoge| hogehoge|
```

これは改行されてないようなテーブル形式での表示が行われており、エラーが消えたものの意図した表示ではありません。

そういうときは、設定ファイルで対応等していきましょう。

```js:.markdownlint.json
{
  "html": false,
}
```

また、ルールそのものを除外したければ、以下のようになります。

```js:.markdownlint.json
{
  "MD033": false,
}
```

# 参考記事

http://raimon49.github.io/2015/05/01/lint-markdown-at-commit.html

この記事自体はmarkdownlintにかけるとエラーが出ます。あしからず。