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

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

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

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

ことが可能となります。

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

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

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

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

DavidAnson/markdownlint
igorshubovych/markdownlint-cli

構文エラー例

例えば

# Some text

## Some text

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

マークダウンファイルの静的解析に際してどういうルールが適用されるかというと、markdownlintパッケージのRulesのページにある一覧よりから確認することが可能です。

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

導入手順

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

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

// 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 を置くことで可能となります。

.markdownlint.json

{
  "whitespace": false
}

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

keyの種類については

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

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

さらに便利に

みなさんがどのようなエディタ、IDEを利用しているかはわかりませんが、VSCodeを利用してるのであれば、markdownlintは、markdownlintによるチェックを強く感じることができる方法の一つです。

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

サンプル

以下のような .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でみると以下のようにエラーが出ます。

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

直してみましょう。

# 何らかのタイトル

## 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|

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

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

.markdownlint.json

{
  "html": false,
}

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

.markdownlint.json

{
  "MD033": false,
}

参考記事

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