[Python]PelicanのMarkdownを拡張する

Python製 静的サイトジェネレータ Pelican の話。
記事は Markdown で書いているのだが、Markdown から生成される HTML の細かい挙動を変えたい、あるいは機能を追加したい場合にどうやってカスタマイズするのか調べてみた。

公式ドキュメントのここに書いてある。
http://docs.getpelican.com/en/3.6.3/content.html?highlight=md_extensions

該当箇所を引用すると、

Pelican also supports Markdown Extensions, which might have to be installed separately if they are not included in the default Markdown package and can be configured and loaded via the MD_EXTENSIONS setting.

というわけで、Markdown パッケージの Extensions を入れることでカスタマイズが可能になる。

設定手順

1. Markdown Extensions をここから探す。
   http://pythonhosted.org/Markdown/extensions/

2. pelicanconf.py に MD_EXTENSIONS という変数を定義して、利用したいパッケージ名を記述する

pelicanconf.pyの例

MD_EXTENSIONS = ['codehilite(css_class=highlight)', 'extra']

Officially Supported Extensions

Extensions のうち、Officially Supported Extensions （中央の表に載っている Extension）については
パッケージ名（markdown.extensions.***** の ***** の部分）を MD_EXTENSIONS に記載するだけで使えるようになる。

Third Party Extensions

それに対して、Third Party Extensions については
まずこちらの Wiki ページからインストールしたい Extension を探す。
https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions
https://python-markdown.github.io/extensions/

2020-04-27追記
https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions は閉鎖されたそうです（コメント#1より報告いただきました）

インストールしたい Extension を見つけたら、pip install でインストールしてから MD_EXTENSIONS に記載する必要がある。

例）http://~ や https://~ から始まる文字列を自動的にリンクにしてくれる mdx_linkify は

$ pip install mdx_linkify

pelicanconf.py

MD_EXTENSIONS = ['mdx_linkify', 'codehilite(css_class=highlight)', 'extra']

注意点

MD_EXTENSIONS について記載されている Settings のページを見てみる。

重要なのは ( ) で書かれている部分。

Note that defining this in your settings file will override and replace the default values. If your goal is to add to the default values for this setting, you’ll need to include them explicitly and enumerate the full list of desired Markdown extensions.

なので、デフォルトでインストールされている Extension （codehilite(css_class=highlight), extra) に 追記する 形で記述する必要がある。

# おすすめの Extension

以下は、ざっと探してみて便利そうだと思った Extension。
( ) 内はパッケージ名

Officially Supported Extensions

• New Line to Break (nl2br)

GitHub と同じく、改行が改行として扱われる。
利用中。毎回末尾に半角スペース2つ入れる必要がなくなって便利。

Third Party Extensions

• Mdx Linkify (mdx_linkify)

上で書いたように、http://~ や https://~ から始まる文字列を自動的にリンクにしてくれる。
利用中。ただの URL を貼るときにラク。

• Markdown Checklist (markdown-checklist)

GitHub ライクな ToDo リストが作れる。
MD_EXTENSIONS には markdown_checklist.extension と書く必要があるので注意。
今のところ使いみちなさそうなので保留。

• mdx_embedly (mdx_linkify)

こちらの記事から見つけた。
PelicanとPython-MarkdownでEmbedlyが使える便利なExtensionを作った

GitHub や Twitter の埋め込みを実現する。
MD_EXTENSIONS には embedly と書く。

便利そうだが、Mdx Linkify を使ってるとうまくいかないらしく保留。

• markdown-newtab (markdown-newtab)

リンクに自動的に target="_blank" がつき、別タブで開くようになる。
MD_EXTENSIONS には markdown_newtab と書く。

これも便利なんだけど、Mdx Linkify でリンクにした方は別タブで開かないので挙動が揃わず、保留。