トップ > CLI > 「markdownlint」を使ってメンテナブルなMarkdownを目指してみる

「markdownlint」を使ってメンテナブルなMarkdownを目指してみる

CLI Tips

markdownlintとは

markdownlintは、Markdownファイル用のLinterだ。そして、markdownlint-cliは、markdownlintをCLIで使うためのラッパーである。

たとえば、README.md という下記のMarkdownファイルがあるとしよう。

プログラミング、完全に理解した。

これをmarkdownlintでチェックすると、こんな警告を出してくれる。

README.md: 1: MD041/first-line-h1 First line in file should be a top level heading [Context: "プログラミング、完全に理解した。"]

この例は、一行目はh1属性を書けという警告である。

Lintルール

雰囲気をつかむために、いくつかのルールを抜粋しよう。

  • MD001 - 見出しレベルは、一度に1レベルだけインクリメントする
  • MD004 - リスト表記で使用する記号を複数混在させない
  • MD010 - タブは使わない
  • MD014 - 出力がないのに、コマンドの行頭に $ を使わない
  • MD024 - 見出しのテキストを重複させない

ほかに、どのようなルールがあるかは、公式ドキュメントを参照してほしい。なお、2018年10月現在、40以上のルールが存在する。

それでは、前置きはこのぐらいにして実際に使ってみよう。

インストール

公式で用意されているのは、npmでインストールする方法である。

$ npm install -g markdownlint-cli

もちろんこれでもいいが、筆者はチームで使いやすいよう、適当なDockerイメージを作成して使っている。

$ docker pull tmknom/markdownlint

使い方

ベーシックな使い方

npmインストールした場合。

$ markdownlint .

Docker版を使う場合。

$ docker run --rm -v "$PWD:/work" tmknom/markdownlint .

ここから先はnpm版のみ載せるが、Docker版を使う場合もほぼ同様である1。

指定したファイルを除外する

特定のファイルのみ除外する場合は、--ignoreオプションを使う。

$ markdownlint --ignore foo.md .

同様に、特定のディレクトリ配下をまとめて除外することもできる。

$ markdownlint --ignore bar/ .

特定のルールを除外する

設定ファイル .markdownlint.json を用意する。すると自動で読み込んで、設定した内容で実行してくれる。記事冒頭で例に出した警告を除外する場合は下記。

{
  "first-line-h1": false
}

設定ファイルは明示的に指定することもできる。前述の内容を myconfig.json というファイルに保存した場合は、--configオプションを使おう。

$ markdownlint --config myconfig.json .

なお、この設定ファイルはYAMLで書くこともできるようだ。

ヘルプ

$ markdownlint --help

  Usage: markdownlint [options] <files|directories|globs>

  MarkdownLint Command Line Interface

  Options:

    -h, --help                                  output usage information
    -V, --version                               output the version number
    -s, --stdin                                 read from STDIN (no files)
    -o, --output [outputFile]                   write issues to file (no console)
    -c, --config [configFile]                   configuration file (JSON or YAML)
    -i, --ignore [file|directory|glob]          files to ignore/exclude
    -r, --rules  [file|directory|glob|package]  custom rule files

バージョン確認

$ markdownlint --version
0.13.0

特定の行のチェックを除外する

特定の行を markdownlint のチェック対象から除外する場合は、Markdownファイルにその設定を直接記述することになる。設定はMarkdownのコメントとして書く。

<!-- markdownlint-disable -->
foo


bar
<!-- markdownlint-enable -->

特定のルールのみ除外することもできる。

<!-- markdownlint-disable MD001 -->
foo

bar
<!-- markdownlint-enable MD001 -->

おわりに

理解しやすいドキュメントを書くことは大切である。そのためにやれることは色々あるが、markdownlintがあれば、Markdownの構造を適切に保つことができ、ドキュメントの内容自体に集中することができるようになる。また、複数人のチームメンバが手を入れても、とっ散らかった状態を抑制できる。

特に、README.mdはソフトウェアエンジニアであれば、多くの人が書くことになるだろう。そんなときのお供に、ぜひmarkdownlintを活用してみよう。

  1. コマンド例の markdownlint を docker run --rm -v "$PWD:/work" tmknom/markdownlint に置換してもらえれば、そのまま動く。↩