Markdown を Lint チェックできる「markdownlint」を試してみた

Markdown 記法は HTML パースしてプレビューするものだが、プレーンテキストで見ても見出しやリストなどの可読性が高いことが特徴だ。

しかし、Markdown 記法や「文章をマークアップする」という概念に乏しい素人が書くと、適切な改行はないわ、デタラメに半角スペースを入れるわで、読めたもんじゃない。

日本語としてまともかどうかは以前紹介した textlint でチェックするとして、

• TextLint を使ってみる

今回は、Markdown 記法が読みやすく適切に書けているかをチェックする markdownlint というツールを使ってみる。

目次

• MarkdownLint
• インストールと基本的な使い方
• 外部ファイルでルールを設定する
• 除外するディレクトリ・ファイルを指定する
• Auto Fix 機能は VSCode 拡張機能で
• 以上

MarkdownLint

MarkdownLint 本体は API しか提供していない。

• GitHub - markdownlint/markdownlint: Markdown lint tool

今回はコレを CLI から実行できる、markdownlint-cli を使ってみる。

• GitHub - igorshubovych/markdownlint-cli: MarkdownLint Command Line Interface

インストールと基本的な使い方

まずは markdownlint-cli をインストールする。今回は簡単にするためグローバルインストールする。

$ npm i -g markdownlint-cli

デフォルトで用意されているルールを使ってそのままチェックを始める、最も基本的な使い方は以下のとおり。

$ markdownlint ./documents/

documents/example1.md: 4: MD022/blanks-around-headers Headers should be surrounded by blank lines [Context: "# 見出しテキスト"]
documents/some-section/example2.md: 112: MD009/no-trailing-spaces Trailing spaces [Expected: 2; Actual: 4]

このようにすると、./documents/ 配下にある Markdown ファイルを全てチェックしてくれる。サブディレクトリも再帰的に調べてくれるので楽チン。

上述の結果だと、

• example1.md は # 見出しテキスト の前後に空行がないよ、のエラー
• example2.md は行末に4つの半角スペースがあるが、改行のためのスペースなら2つで良いよ、のエラー

が検出されている。

外部ファイルでルールを設定する

MarkdownLint が対応しているルールの一覧は以下で確認できる。

• markdownlint/Rules.md at master · DavidAnson/markdownlint · GitHub

このルールを個別に無効にしたり、ルールで縛る内容を変更したりできる。CLI で使う時は何でも良いが、VSCode 拡張機能との連携を考慮して .markdownlint.json というファイル名にしておこう。

内容は JSON 形式で記述する。以下は MD001、見出しレベルを1つずつ下げているか (見出しレベルをスキップしていないか) をチェックするルールを無効にした。

{
  "MD001": false
}

ルール名は ID だけでなくエイリアスも振られているので、MD001 のルールを無効にするには、以下のように書いても同じだ。

{
  "header-increment": false
}

JavaScript コメントを書いても認識はしてくれるが、パースエラーというワーニングが表示されて精神衛生的に良くない。無効なプロパティは無視されるので、ルール ID をコメントで記述し、エイリアスの方で実際にルールを指定するとメンテしやすいかも。

{
  "//": ".markdownlint.json : https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md",
  "//": "--------+-----------------------------------------",
  "//": " ID     | Rules                                   ",
  "//": "--------+-----------------------------------------",
  "//": "MD003",   "header-style": { "style": "atx" },
  "//": "MD004",   "ul-style": { "style": "dash" },
  "//": "MD009",   "no-trailing-spaces": {
                     "br_spaces": 2
                   },
  "//": "MD012",   "no-multiple-blanks": { "maximum": 2 },
  "//": "MD013",   "line-length": false,
  "//": "MD014",   "commands-show-output": false,
  "//": "MD024",   "no-duplicate-header": false,
  "//": "MD026",   "no-trailing-punctuation": { "punctuation": ".,:!?" },
  "//": "MD033",   "no-inline-html": false,
  "//": "MD035",   "hr-style": { "style": "---" },
  "//": "MD041",   "first-line-h1": false,
  "//": "MD044",   "proper-names": {
                      "names": [
                        "JavaScript"
                      ],
                      "code_blocks": false
                    },
  "//": "--------------------------------------------------"
}

こんな感じ。逆に見づらいかな…。

設定ファイルを利用して Lint チェックを行うには以下のように呼ぶ。

$ markdownlint ./documents/ --config ./.markdownlint.json

除外するディレクトリ・ファイルを指定する

Lint チェックの対象外とするディレクトリやファイルを指定するには以下のようにする。--ignore オプションは複数書ける。

$ markdownlint ./documents/ --config ./.markdownlint.json --ignore ./documents/node_modules/ --ignore ./documents/memo.md

Auto Fix 機能は VSCode 拡張機能で

markdownlint-cli には Auto Fix (自動修正) 機能はない。自動修正をしたい場合は、VSCode エディタの拡張機能「markdownlint」を使おう。

• markdownlint - Visual Studio Marketplace

コレをインストールしたら Markdown ファイルを開き、緑の波線が引かれている箇所を選択する。すると電球のアイコンが表示されるので、それをクリックするか Ctrl + . (Cmd + .) を押下してコンテキストメニューを表示する。メニューから「Click to fix this violoation...」を選択すると自動修正できる。

残念ながら、ファイル内の指摘箇所を全て一気に修正したり、対象ディレクトリ内の違反箇所を一括で自動修正したりはできない模様。普段からよく読み返してちゃんと書けということか。

以上

TextLint と MarkdownLint で、Markdown ファイルの形式的な日本語・書式チェックはできるようになったであろう。