[Python]PelicanのMarkdownを拡張する

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

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

該当箇所を引用すると、

> Pelican also supports [Markdown Extensions](http://pythonhosted.org/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](http://pythonhosted.org/Markdown/) パッケージの Extensions を入れることでカスタマイズが可能になる。

# 設定手順

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

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

```python:pelicanconf.pyの例
MD_EXTENSIONS = ['codehilite(css_class=highlight)', 'extra']
```


### **Officially Supported Extensions**

Extensions のうち、[Officially Supported Extensions](http://pythonhosted.org/Markdown/extensions/#officially-supported-extensions) （中央の表に載っている Extension）については
パッケージ名（`markdown.extensions.*****` の `*****` の部分）を `MD_EXTENSIONS` に記載するだけで使えるようになる。


### **Third Party Extensions**

それに対して、[Third Party Extensions](http://pythonhosted.org/Markdown/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](https://qiita.com/zaki-yama/items/b5f53dd24234cea092cd#comment-956eb560bf327a772d11)より報告いただきました）

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

例）http://~ や https://~ から始まる文字列を自動的にリンクにしてくれる [mdx_linkify](https://github.com/daGrevis/mdx_linkify) は

```zsh
$ pip install mdx_linkify
```

```python:pelicanconf.py
MD_EXTENSIONS = ['mdx_linkify', 'codehilite(css_class=highlight)', 'extra']
```




# 注意点

`MD_EXTENSIONS` について記載されている [Settings](http://docs.getpelican.com/en/3.6.3/settings.html#basic-settings) のページを見てみる。

![SS 2016-01-09 18.42.23.png](https://qiita-image-store.s3.amazonaws.com/0/36518/724c3629-aafa-a7e3-4c79-216ed7f20592.png)


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

> 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`) に **追記する** 形で記述する必要がある。

<br />
# おすすめの Extension

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

### **Officially Supported Extensions**

- [New Line to Break](https://pythonhosted.org/Markdown/extensions/nl2br.html) (`nl2br`)

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

### **Third Party Extensions**

- [Mdx Linkify](https://github.com/daGrevis/mdx_linkify) (`mdx_linkify`)

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

- [Markdown Checklist](https://github.com/FND/markdown-checklist) (`markdown-checklist`)

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

- [mdx_embedly](https://github.com/yymm/mdx_embedly) (`mdx_linkify`)

こちらの記事から見つけた。
[PelicanとPython-MarkdownでEmbedlyが使える便利なExtensionを作った](https://muunyblue.github.io/5747a0021eb349e9c8d3667cf1a5e9ec.html)

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

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


- [markdown-newtab](https://github.com/Undeterminant/markdown-newtab) (`markdown-newtab`)

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

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