「markdownlint」を使ってMarkdown記法の構文チェックを行う（Vimのaleプラグインと組み合わせるともっと便利に）

2020-01-11Bash,JavaScript,Vim

はじめに

手に馴染むエディタを使いコードを書きながら、同じぐらいドキュメントを書いてます。

アプリケーションの概要、報告書、ブログからメールに至るまで、最近はMarkdown形式で記載してそれぞれのビューアあるいはコンバータで変換して文字を起こすことが多くなっています。

Markdown記法を利用することのメリット

  • 執筆効率がよい
    • HTMLのようにタグを書かなくて良いためタイピング量が減る
    • 簡単なメモでも早く綺麗に書ける
  • 統一したドキュメント形式を保てる
  • 汎用性が高い
    • 関連ツールや利用できるサービスが多い
  • 段落など見た目が統一される
    • h1 / h2 / h3 / pre / li / bold ...

Markdown記法は自由が多い

Markdown記法の習得は非常に容易です。
実際僕も一日ほど使ったぐらいで移行することができました。
理由の一つとして規約の少なさがあげられます。

Markdown記法は自由度を構文チェックで補う

自由度が高いがゆえに、統一感のないドキュメントが出来上がりがちです。
例えばHTMLの文書構造として、 h1 タグの次には h2 タグが登場するべきであり、 h3 タグが登場してはおかしいですね。
同様に # でタイトルを記載したあとに ### タイトルが来るとおかしいわけです。 # タイトルがないというのもやはり同様におかしいですね。

自由度の高いMarkdown記法ですが、
構文チェックを行うことで、弱点を補うことができます。

Markdown記法の構文チェックツール「markdownlint」を使う

僕は 「markdownlint」 というLintツールを利用しています。

導入手順

事前準備

Node.js製のツールとして提供されているため、Node.jsのインストールが必要です。
以下のエントリを参照すればすぐにインストールが可能です。

markdownlintのインストール

npm コマンドでインストールします。

$ npm install -g markdownlint markdownlint-cli

セットアップは以上になります。

使ってみる

以下のコマンドで実行できます。

$ markdownlint <対象となるmdファイル>

※「nvm」を使ってNode.jsをインストールした手順を利用したため、markdownlintコマンドのインストールパスは以下のようになりました。
※Node.jsのインストールの仕方で変わりますのでご注意ください。

# (例)
$ which markdownlint
/root/.nvm/versions/node/v12.2.0/bin/markdownlint

適当なMarkdownファイルを作成し、構文チェックをしてみます。

$ cat <<'EOF' >test.md
## タイトル2
おはようございます

#### タイトル4
* こんにちわ
* こんばんわ
EOF
$ cat test.md
## タイトル2
おはようございます

#### タイトル4
* こんにちわ
* こんばんわ

コマンドを実行しチェックを行います。

$ markdownlint test.md
test.md: 1: MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## タイトル2"]
test.md: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "## タイトル2"]
test.md: 4: MD001/heading-increment/header-increment Heading levels should only increment by one level at a time [Expected: h3; Actual: h4]
test.md: 4: MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "#### タイトル4"]
test.md: 5: MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "* こんにちわ"]
test.md: 8: MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]

大量にエラーが出てきました。
こちらをメッセージどおりに修正し、再度チェックを行います。

$ cat <<'EOF' >test.md
# タイトル2

おはようございます

## タイトル4

* こんにちわ
* こんばんわ
EOF
$ cat test.md
# タイトル2

おはようございます

## タイトル4

* こんにちわ
* こんばんわ
$ markdownlint test.md

エラーが表示されなくなりました。

ひとこと

僕はVimでMarkdownファイルを編集しているときに自動的に構文チェックが行われるようにしています。
markdownlint をインストールした上で、Vimの w0rp/ale というプラグインをインストールすれば環境構築は完了です。

2020-01-11Bash,JavaScript,Vim