MoinMoinでMarkdownを使う

Markdown と、その拡張記法である Github Flavored Markdown (GFM)、および Markdown Extra を同時に使いたい。
また、Markdown では html タグを直接記述することができるが、wiki で許可するには危険なので禁止したい。

Python 用の Markdown パーサー (python-markdown) があり、各種設定で上記が実現できる。

MoinMoin側プラグイン

既に MoinMoin 用に、python-markdown に丸投げするパーサープラグイン (Markdown Parser) がある。
これを一部改変して使う。

text_markdown.py

変更点

• パーサーに渡す引数を wikiconfig.py 中で指定できるようになった (markdownargs = {'option': 'value', })
• html タグを直接記述できなくするため、デフォルトで html タグをエスケープするようにした (safe_mode='escape')

python-markdown の設定

python-markdown は Extension で機能を拡張/変更することができる。
これを使って GFM 対応等々の拡張を施す。

記法の拡張

GFM, Markdown Extra を導入したい。

GFM について

• Standard Markdown との違い 1
• Standard Markdown との違い 2
• 記法チートシート

Markdown Extra について

• Standard Markdown との違い

Markdown Extra

python-markdown にデフォルトで拡張機能が入っているので、有効にするだけでよい。
上記自作パーサーでは wikiconfig.py 中でパーサーに渡す引数を設定できるのでそれを利用する。

    markdownargs = {
        'extension': ['extra']
    }

もちろん、MoinMoin 側のプラグイン自体をいじって直接に引数を渡してやってもよい。

GFM

py-gfm を導入する。python-markdown 用の extension.
デフォルトでは入っていないので自前で取得してくる必要がある。

適当な場所にレポジトリを clone する。

git clone https://github.com/dart-lang/py-gfm.git

clone したレポジトリへのパスを sys.path に追加して import できるようにする。
例えば、wikiconfig.py にそのように追記する。

    sys.path.insert(0, 'path/to/py-gfm')

さらに、wikiconfig.py 等でパーサーに渡す引数を設定する。

    markdownargs = {
        'extensions': ['gfm']
    }

参考記事

• MoinMoin で Markdown (Github Flavored Markdown) を使う (tototoshi の日記)
• Python で Github Flavored Markdown をレンダリングする (tototoshi の日記)

その他の拡張

他にもいくつかビルトインの extension が用意されている。
また、他のサードパーティー製 extension もある。

html タグの禁止

パーサーへの引数 safe_mode を適切に設定してやればよい。デフォルトでは許可するようになっている。
上記自作プラグインでは safe_mode=’escape’ をデフォルトとした。
変更するには wikiconfig.py 中で以下のようにする。

    markdownargs = {
        'safe_mode': '設定値'
    }

Pygments用CSS

ここまで済めばほぼちゃんとレンダリングされるが、Code Highlighting の色分けがまだうまくいかない。
Code Highlighting に使われている Pygments は MoinMoin 本体でも使われているが、Moin 書式のパーサーから呼ぶ場合と出力される html が異なり、Markdown から使う場合は追加で css が必要となる。

cssを書いて配置

pygments 公式にある方法で好みのスタイル用の CSS を出力し、 ./MoinMoin/web/static/htdocs/common/ あたりに入れておく。

$ pygmentize -S monokai -f html -a .highlight > pygments.css 

pygments 1.6 では以下のスタイルがデフォルトで使用可能。

['monokai', 'manni', 'rrt', 'perldoc', 'borland', 'colorful', 'default', 'murphy', 'vs', 'trac', 'tango', 'fruity', 'autumn', 'bw', 'emacs', 'vim', 'pastie', 'friendly', 'native']

wikiconfig.py

追加した css を全ての場合で読み込むように、wikiconfig.py に一行追加する。

    stylesheets = [('all', url_prefix_static + '/common/pygments.css'),]

これでコードブロックの色分けが動作するようになった。