Markdown lint toolでMarkdownファイルの構文のLintをチェック

By raimon, 2017-10-29(日), in category Ruby

CI, Git, Markdown, Ruby

継続的にMarkdownファイルの構文チェックを実施させたい時はRubyのMarkdown lint tool(以降「Markdownlint」)を利用する。

Lint設定の変更方法や、CIサービスとの連携方法についてまとめる。

インストール

MarkdownlintはRubyGemsで公開・配布されているため gem または bundle コマンドを用いてインストールする。

例えば bundle であれば、次のように Gemfile にRubyGemsでの公開名「mdl」を記述する。

source 'https://rubygems.org'

gem 'mdl'

Bundlerでローカル環境にインストールする。

$ bundle install --path vendor/bundle

インストール後、Bundlerを通して mdl コマンドがローカル環境で実行可能になる。

$ bundle exec mdl --help
Usage: mdl [options] [FILE.md|DIR ...]
    -c, --config FILE                The configuration file to use
    -g, --git-recurse                Only process files known to git when given a directory
    -i, --[no-]ignore-front-matter   Ignore YAML front matter
    -l, --list-rules                 Don't process any files, just list enabled rules
    -r, --rules RULE1,RULE2          Only process these rules
    -u, --rulesets RULESET1,RULESET2 Specify additional ruleset files to load
    -a, --[no-]show-aliases          Show rule alias instead of rule ID when viewing rules
    -w, --[no-]warnings              Show kramdown warnings
    -d, --skip-default-ruleset       Don't load the default markdownlint ruleset
    -s, --style STYLE                Load the given style
    -t, --tags TAG1,TAG2             Only process rules with these tags
    -v, --[no-]verbose               Increase verbosity
    -h, --help                       Show this message
    -V, --version                    Show version

リンティングの実行

リンティングの実行は、 mdl コマンドの引数として、Markdownファイルや文書の存在するディレクトリ名を渡すだけである。

$ bundle exec mdl docs

この時、Markdownlintのチェック設定として、ツール側の推奨するルールが適用される。

例えば、推奨ルールではリストのインデントにおいて2 spacesを推奨しているため、4 spacesやハードタブを採用しているMarkdown文書では、次のようなエラーが検出される。

MD007 Unordered list indentation

Lintルールの無視設定やカスタマイズ

自分達のプロジェクトで採用するルールと合わなくて無視したい場合は mdlrc というファイルを作成し、無視したいルール名を ~ (チルダ)で明示する。

rules "~MD007"

そしてリンティング実行時に上記の設定ファイルを -c オプションに指定すれば良い。複数のルール名を記述したい場合はカンマ区切りで並べれば全てのルールについて有効/無効を指定できる。

$ bundle exec mdl -c mdlrc docs

デフォルトの推奨ルールを全て継承した上で、特定のルールだけ設定を変えたい場合は style.rb のようなファイルを作成する。例えばリストのインデントを4 spacesだったら正としてチェックさせたい時は、次の内容となる。

all
rule 'MD007', :indent => 4

リンティング実行時には、このスタイルファイルを -s オプションに指定する。スタイルファイルの詳細はCreating stylesを参照のこと。

CIサービスで自動実行させる

ローカル環境でだけMarkdownファイルをチェックできるだけでも助かるのだが、やはりCIサービスと連携して自動実行させたい。

Travis CIであれば、CI設定ファイル .travis.yml は次のような内容になるだろう。無視設定やスタイル設定は script: のコマンド行で各々のプロジェクトに合わせて指定させると良い。ここでは例として、先に挙げた4 spaces indentのスタイル設定ルールを採用して自動チェックさせる。

language: ruby
rvm:
  - 2.4
script:
  bundle exec mdl -s style.rb docs

サンプルとして、このCI設定ファイルを使ってTravis CIと連携し、Pull Requestを投げたら自動でルール違反が検出され、修正後にCIジョブをPassしてマージされるまでの流れを記録に残した。

また、この記事を書いて以降、CIサービスの主流はGitHub Actionsに移行しつつあるため、ActionsでのCI設定ファイルも例として記載しておく。

name: Ruby

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  test:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        ruby-version: ['2.6', '2.7', '3.0']

    steps:
    - uses: actions/checkout@v2
    - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: ${{ matrix.ruby-version }}
        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
    - name: Run tests
      run: bundle exec mdl -s style.rb docs

まとめ

他の実装