【mkdocs】インストールしたテーマが使えない
homebrewでインスコしたmkdocsで既存テーマをインストールして使おうとしたら、なんかてこづったのでその失敗談と解決法の譚。
何も考えたくないならば、brewじゃなくてpipでmkdocsをインストールした方が良さげ。
追記：pipでインストールした方が良いです。pythonが複数インストールされている場合は、どのpythonのパッケージ管理しているpipなのかに注意してインストールしましょう。
環境・前提
- macOS
pipじゃなくて、brew install mkdocsでインストールした。- mkdocsは普通に使える（
madocs serveとか）
install mkdocs with homebrew
brew install mkdocs
ほんで、
% mkdocs --version mkdocs, version 1.1 from /usr/local/Cellar/mkdocs/1.1/libexec/lib/python3.8/site-packages/mkdocs (Python 3.8)
こんな感じ。
失敗例：テーマのインスコ
例えば、 ivory というテーマを使うために、pip コマンド1 でそれをインストールする。
pip install mkdocs-ivory
ちゃんとインストールできたかを確認する。
% pip list Package Version ------------ --------- certifi 2019.9.11 chardet 3.0.4 idna 2.8 mercurial 5.2 mkdocs-ivory 0.4.2 <-- インストールされてる pip 20.0.2 PixivPy 3.4.0 requests 2.22.0 setuptools 46.0.0 urllib3 1.25.3 wheel 0.34.2
こんな感じで、インストールされているパッケージ一覧が表示される。
mkdocs-ivory もちゃんとインストールされている。
では、このテーマを使うように mkdocs.yml を編集する。
theme: ivory
プロジェクトのディレクトリに移動して、mkdocs serve でサーバを起動。
すると、次のようなエラーが出る。
% mkdocs serve INFO - Building documentation... ERROR - Config value: 'theme'. Error: Unrecognised theme name: 'ivory'. The available installed themes are: mkdocs, readthedocs Aborted with 1 Configuration Errors!
インストールされとるテーマは mkdocs と readthedocs だけやで？って言われている。
以上、失敗例。
原因
原因は単純で、パスが通っていて、テーマをインストールしたpipが管理しているpythonと、mkdocsが使っているpythonが異なるというだけ。
ただ、ここで単に、 pip あるいは python のバージョンが異なっていただけかと思って、mkdocsが使っているpythonのバージョンに合ったpipコマンドでmkdocsテーマをインストールし直したが、しかし同様のエラーが出てしまうので少し混乱してしまった。
どうやら、brewでmkdocsをインストールすると、PCに既にpythonがインストールされていようがなかろうが、mkdocs専用のpythonとそのパッケージ管理pipをわざわざ再インストールしてしまうようである2。
つまり、mkdocsが使うpythonのためのライブラリを管理するには、brewによってmkdocsと一緒にインストールされた方のpipを使わなければいけない。
解決
mkdocs が使っているpythonを特定する。
% brew list mkdocs /usr/local/Cellar/mkdocs/1.1/bin/mkdocs /usr/local/Cellar/mkdocs/1.1/libexec/bin/ (21 files) /usr/local/Cellar/mkdocs/1.1/libexec/lib/ (1608 files) /usr/local/Cellar/mkdocs/1.1/libexec/.Python
pythonがありそうなディレクトリに移動。そして見つける。
% cd /usr/local/Cellar/mkdocs/1.1/libexec/bin/ % ls p* pasteurize* pip3* python@ python3@ pip* pip3.8* python-config* python3.8*
ここにある python3.8 がmkdocsが使っているpythonであり、 pip3.8 がそのパッケージを管理している。
パッケージリストを見てみると
% ./pip3.8 list Package Version ---------- ------- click 7.1.1 future 0.18.2 Jinja2 2.11.1 livereload 2.6.1 lunr 0.5.6 Markdown 3.2.1 MarkupSafe 1.1.1 mkdocs 1.1 <-- mkdocsがいる nltk 3.4.5 pip 20.0.2 PyYAML 5.3.1 setuptools 46.1.3 six 1.14.0 tornado 6.0.4 wheel 0.34.2
のように表示され、mkdocsがインストールされていることがわかる。
このpipを使ってmkdocsのテーマivoryをインストールする。
% ./pip3.8 install mkdocs-ivory Collecting mkdocs-ivory Using cached mkdocs_ivory-0.4.2-py3-none-any.whl (10 kB) Installing collected packages: mkdocs-ivory Successfully installed mkdocs-ivory-0.4.2 % ./pip3.8 list Package Version ------------ ------- click 7.1.1 future 0.18.2 Jinja2 2.11.1 livereload 2.6.1 lunr 0.5.6 Markdown 3.2.1 MarkupSafe 1.1.1 mkdocs 1.1 mkdocs-ivory 0.4.2 <-- installed nltk 3.4.5 pip 20.0.2 PyYAML 5.3.1 setuptools 46.1.3 six 1.14.0 tornado 6.0.4 wheel 0.34.2
これで、プロジェクトディレクトリ戻って mkdocs serve すれば、ちゃんとテーマが適用されたサイトがビルドされる。
結局
mkdocsのテーマをインストールするたびにpipを探しに行くのは面倒なので、テキトーにエイリアスを作る。
bashなら ~/.bash_profile に、zshなら ~./zshrc に以下の行を追加する。
alias pip-mkdocs='/usr/local/Cellar/mkdocs/1.1/libexec/bin/pip3.8'
設定の変更を反映。
source ~/.bash_profile
あるいは
source ~./zshrc
これでどこでも pip-mkdocs と打てば、mkdocsのためのpythonのためのpipが使える。
まあ、これで問題はないけど、面倒ならbrewじゃなくて既にPCにインストールされているpipでmkdocsをインストールした方がいいかもしれない。
つまり、公式サイトの Manual Instllation に従ってmkdocsをインストールする。
