コンテンツにスキップ

mkdocsのマクロプラグインを使う

mkdocs のマクロプラグインを使用することで、Python の関数を呼び出して
その結果を表示できるようにできます。
というのを前からあるのは知ってましたが、mkdocs をバージョンアップするついでに
使い方を色々調べてみました。

1
pip install mkdocs-macros-plugin

まずはプラグインを pip でインストールします。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
plugins:
  - git-revision-date-localized:
      type: iso_datetime
      locale: ja
  - search:
      lang:
        - en
        - ja
  - awesome-pages
  - macros

そしてpluginsに macroを追加します。
これで準備は完了。

次に呼び出し用のpythonを作ります。
mkdocsのプロジェクト直下に main.py を準備して、そこに

1
2
def define_env(env):
    # マクロはここに書く

define_env 関数を作ります。
マクロプラグインが呼び出すための関数で、
マクロに必要な値がこの関数の引数として渡されます。

マクロを作る

マクロとは、

1
{{hoge()}}

こんな感じで {{ }} で main.py の define_env に書かれた関数を呼び出して
そのreturnを表示できるようになります。

1
2
3
    @env.macro
    def fontstyle(comment, size=1.0, color='#000000'):
        return f'<div style="font-size:{size * 100}%;color:{color}">{comment}</div>'

例えばこんな感じの定義を作り、@env.macro のデコレーターをつけます。

1
2
3
4
    def testHoge():
        return 'return hogehoge
    # デコレーターを使わない場合
    env.macro(testHoge, 'hogevalue')

あるいは、デコレーターを使わない場合は、env.macroの第１引数で関数を渡し
第２引数で呼び出し用の {{return hogehoge}}に指定する文字列を指定しておきます。

出来上がったマクロは、

1
{{fontstyle('ここに文字を書く',1.2,'#ff0000')}}

mkdocsにこのように書くと

ここに文字を書く

このように文字サイズを変えることができます。
フォントサイズや色はmarkdownだと難しいので、こうやってマクロをかけるのは
とても便利です。

フィルターを作る

フィルターとは、 Jinja2 の機能で

1
{{name|lower}}

こんなかんじで {{}} の1つ目の変数を2つ目の定義されたフィルターで変換して
結果を表示させることのできる機能です。

1
2
3
    @env.filter
    def twitter(url):
        return f'<blockquote class="twitter-tweet"><a href="{url}"></a></blockquote><script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>'

フィルターの作り方はかんたんで、
デコレーターで @env.filterをつけた関数を作り、入力の値を引数として
その結果を return します。

1
{{'https://twitter.com/fereria/status/1164544426967875584'|twitter}}

上のTwitterフィルターは、値でTwitterのURLを渡すと

Twitterを埋め込みにしてくれます。
引数を必要としない修飾はフィルターを使うと良さそうです。

ついでにマクロ前提だと {{これ}} のカギカッコを表示するのも
面倒だったので、そういうマクロを書いてみました。

今は単純にタグを作るためのマクロがメインですが
return で文字列を返せば何でもできるので、mkdocsのかゆいところをPythonで書いたり
他のAPIを叩いて結果をmkdocsに表示するみたいな使い方ができそうです。