MkDocs で .git や node_modules など指定ディレクトリを exclude(除外) したい

MkDocs でリポジトリ中の Markdown ファイルたちを HTML に変換したいのだが、.git やら node_modules やら巨大なテンポラリフォルダが邪魔なせいで MkDocs のビルドが終わらない。

exclude できないかと思って、調べて、対処法にたどり着いたのでメモ。

対処方法

mkdocs-exclude プラグインを使う。

(設定1/2) インストール

1: MkDocs が古いならバージョンアップしておく

MkDocs が古いと mkdocs-exclude が動作しないので、先にバージョンアップしておく。

私の場合、元々こんな感じだった。

$ pip freeze | grep mkdocs
mkdocs==0.17.4
mkdocs-alabaster==0.7.4
mkdocs-material==2.9.1

これに対して mkdocs を upgrade する。

$ pip install mkdocs --upgrade
...
mkdocs-material 2.9.1 has requirement tornado<5, but you'll have tornado 5.1.1 which is incompatible.
...

エラーが一つ出ている。mkdocs-material 2.9.1が古いぞオイ(tornado ver 5 以下が必要なのに、あんた今は ver 5.1.1 になってんで) とのこと。

つまり mkdocs-material も古いので upgrade する。

$ pip install mkdocs-material  --upgrade

この時点でこうなった。

$ pip freeze | grep mkdocs
mkdocs==1.0.4             ★from 0.17.4
mkdocs-alabaster==0.7.4
mkdocs-material==4.0.1    ★from 2.9.1

もう一度 pip install mkdocs --upgrade を行って、エラーが出ないことを確認。これで upgrade はおわり

2: mkdocs-exclude をインストールする

apenwarr/mkdocs-exclude をインストールする。

$ pip install mkdocs-exclude

(設定2/2) mkdocs.yml に設定を書く

glob が使えるので楽。

以下は .git、coverage、node_modules の三つのディレクトリを弾く例。

plugins:
  - exclude:
      glob:
        - '**/.git/*'
        - '**/coverage/*'
        - '**/node_modules/*'

設定完了

これで指定ディレクトリが除外されてビルドが走るはず。

1分経っても終わらないビルドが10秒以内で終わるようになった。助かる。

(余談) あってもいい機能なのになんで MkDocs 公式はサポートしない?

MkDocs の Issues で議論されてる。

色々あるけど、一言で言うなら https://github.com/mkdocs/mkdocs/issues/1152#issuecomment-285083310 ここの

Finally, if we were to change the current behavior, it would break a lot of users existing sites. So while I can see an argument for an adjustment here, it is not likely to overcome the backward compatibility argument to leave things as-is.

これだろうか。よくわからんが今の仕組み的に、exclude 機能を入れようと思ったら後方互換性壊れちゃうみたい。

で、今年の 1 月になって、apenwarr さんという人が プラグインをつくった

I created a mkdocs-exclude plugin that uses the new plugin API to do what's requested in this bug: https://github.com/apenwarr/mkdocs-exclude

plugin API として exclude 機能が追加されたから実現できたみたい。あざっす。助かりました。