プラグインを自作してみよう

ここでは、MkDocs のプラグインを自分で作る手順を説明します。ものすごく簡単なサンプルプラグインを作って、自分のサイトに反映されるところまでを見ていきます。

プラグイン用のファイルを作ろう

MkDocs のプラグインは、Python で書きます。また、ただ書くだけではなく、パッケージ化をする必要もあります。順番に手順を見ていきます。

プラグインの本体ファイルを作ろう

まずは、プラグインの本体部分を作りましょう。次のようなファイル構成だとしましょう。

plugin
└── my_first_plugin
    └── sample.py

この sample.py に、次のように書いていきます。

from mkdocs.plugins import BasePlugin

class SamplePlugin(BasePlugin):
    def on_pre_build(self, config):
        print('Hello World!')

まず、プラグインは、mkdocs.plugins.BasePlugin クラスを継承して、サブクラスを作ります。ここでは、SamplePlugin クラスを作りました。

このクラスには、「どのタイミングで何をするか」を書いていきます。ここでは、on_pre_build 、つまり、ビルドを行う直前のタイミングで処理を行う、と指定しています。このタイミングで Hello World! と表示することにしました。

どのイベントで、どういう引数を受け取って、何を返すか、というのは、公式サイトにまとめられています。

これで、プラグインの本体の設定は一旦おしまいです。

パッケージの情報を書こう

プラグインを使うには、パッケージ化をする必要があります。そのために、次のようにファイルを2つ追加します。

plugin
├── my_first_plugin
│   ├── __init__.py
│   └── sample.py
└── setup.py

setup.py は、パッケージ化を行うための設定などを書いたファイルで、__init__.py は、このフォルダがパッケージ化に使う特殊なフォルダだよ、と示すためのもの、と考えておけばいいでしょう。

__init__.py は、空ファイルでかまいません。setup.py には、次のように書きます。

from setuptools import setup

setup(
    name='xxxxx',
    packages=['my_first_plugin'],
    entry_points={
        'mkdocs.plugins': [
            'my_plugin = my_first_plugin.sample:SamplePlugin',
        ]
    },
)

必要最低限の設定だけ行っています。name は、pip list で表示される名前です。packages は、プラグインのファイルが入っているフォルダです。これらは、Python での一般的な設定です。

entry_points では、MkDocs でプラグインを認識するための設定を記載します。mkdocs.plugins と書いた後に、

プラグイン名 = プラグインへのパス:クラス名

と書きます。上の設定では my_first_plugin.sample:SamplePlugin としていますが。これは、my_first_plugin フォルダにある、sample.py ファイルの中にある SamplePlugin クラス、を指定していることになります。プラグイン名は、mkdocs.yml で指定するときに使う名前です。

これで、パッケージ情報の設定が終了です。

プラグインの動作確認を使用

さて、では実際にプラグインを使えるように指定みましょう。

まず、setup.py のあるフォルダで、以下を実行してみましょう。

> python setup.py develop

これは、開発用にインストールする、という命令です。これを実行すれば、次のようなファイルができた、とメッセージが出てきます。人によって、場所は違うでしょう。

C:\users\user.conda\envs\mkdocs\lib\site-packages\xxxxx.egg-link

ここで、pip list を実行すると、setup.py で設定した名前が見つかるはずです。

ここの site-packages フォルダを見に行くと、pip でインストールしたものがたくさん見つかるでしょう。 mkdocs フォルダも見つかるはずです。しかし、setup.py で設定した名前のフォルダは作成されていません。

実は、これは先ほど develop をつけて setup.py を実行したからです。これをつけて実行すると、例えば sample.py 内のファイルの中身を変えた場合、すぐにこのプラグインを使っているサイトにも反映されます。

もし develop をつけずにインストールしたら、プラグインの中身を変えるたびにインストールをしなおさないといけないので、面倒です。自分でプラグインを作る場合は、開発用オプション develop をつけて実行するようにしましょう。

さて、これで、もうプラグインは使えるようになっています。mkdocs.yml ファイルで次のように設定しましょう。

plugins:
    - search
    - my_plugin

ここで設定する名前は、setup.py の entry_points 内で指定した名前です。こうして mkdocs serve を実行すれば、ターミナル上に Hello World! と表示されるはずです。また、sample.py を修正して mkdocs serve を再度実行すれば、すぐに反映されているはずです。

ちなみに、アンインストールしたい場合は、次を実行します。

> python setup.py develop -u

おわりに

ここでは、MkDocs のプラグインを作って、実際に自分のサイトに反映させる方法を見てきました。プラグインを自分で作るのは大変ですが、Python が書けるならぜひ挑戦してみましょう。