プラグインを使おう

MkDocs はデフォルトでもいろいろなことができますが、さらに機能を追加したいこともあるでしょう。そうした場合に、プラグインを使えば、欲しい機能を追加で使えるようになります。

ここでは、プラグインの使い方を見ていきます。

プラグインのインストール

プラグインを使うためには、まずインストールをする必要があります。MkDocs にもとから入っているものは mkdocs.yml で指定するだけで使えるようになりますが、他の人が作ったプラグインは、事前にインストールしなくてはいけません。

インストールは、次のように pip を使います。

> pip install mkdocs-foo-plugin

これで、 mkdocs-foo-plugin というプラグインのインストールが終わります。どのような名前でインストールできるかは、各プラグインのサイトで確認しましょう。

他の人が作ったプラグインは、MkDocs Plugins というページでまとめられています。便利そうなものもありますが、ほとんど使われていないものや、最近まったく更新されていないもの（放置状態のもの）もあるので、注意してインストールしましょう。

アンインストールは、次のように行います。

> pip uninstall mkdocs-foo-plugin

MkDocs 特有のコマンドではなく、pip の一般的なコマンドです。

プラグインをインストールしたら、今度はサイトで使うための設定を行いましょう。この設定を行わないと、サイトへは反映されません。

プラグインを使うには、mkdocs.yml 内で、次のように書きます。

plugins:
    - search
    - mkdocs-foo-plugin

search は、検索するためのプラグインで、MkDocs テーマや Read the Docs テーマ、Material テーマなどではじめから使えるようになっています。それに加えて mkdocs-foo-plugin を使うには、上のようにします。

なお、search を書かないと、search プラグインは使えなくなる点に注意しましょう。デフォルトで使えるプラグインに追加されるわけではないので、明示的に指定する必要があります。

プラグインによっては、オプションを指定できるものもあります。「オプション名: 値」と書きます。例えば、次のように書きます。

plugins:
    - search
    - mkdocs-foo-plugin:
        aaa: xxx

プラグインの最後にもコロン「:」をつけないといけないので注意しましょう。

次のように書けば、すべてのプラグインを除外することができます。

plugins: []

ここでは、他の人が作ったプラグインをインストールし、使えるようにする設定方法を見てきました。MkDocs が提供していない機能が使えるようになるものもあるので、探してみましょう。