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 で議論されてる。
- site_dir contains folders (and subfolders) from doc_dir though not specified in mkdocs.yml · Issue #1152 · mkdocs/mkdocs
- Building hidden pages · Issue #699 · mkdocs/mkdocs
色々あるけど、一言で言うなら 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 機能が追加されたから実現できたみたい。あざっす。助かりました。