MoinMoin で Markdown を使う

軽量マークアップ言語の一つ Markdown は読みやすく、また GitHub 等で使われているため使用人口が多い。これを MoinMoin で使いたい。
目指したものは以下の通り。

• Markdown の拡張記法である Github Flavored Markdown (GFM) と Markdown Extra を同時に使いたい。
• Markdown では html タグを直接記述することができるが、wiki で許可するには危険なので禁止したい。
• MoinMoin 独自のリンク記法、埋め込み記法、マクロ、パーサー変更機構を使いたい。
  (リンクと埋め込み記法は実装完了。TODO: マクロとパーサの実装)

プラグイン機構を備えた Python 用 Markdown パーサー (python-markdown) があり、Markdown から html を生成してくれる。MoinMoin 側にも python-markdown とのインターフェイスとなるプラグインがあり、制限付きながら MoinMoin で Markdown を扱うことができる。

拡張記法

Markdown はオリジナルのままでは出来ることが少ないので、多くの拡張記法が存在する。その中で代表的なものは下に挙げた二つで、他の実装に取り入れられている部分も多い。

GitHub Flavored Markdown (GFM)

サードパーティーによる Extension で対応できる。(py-gfm)

• 記法の拡張
• 独自機能
• 記法チートシート

Markdown Extra

python-markdown に標準で入っている Extension により対応。

• 記法の拡張

MoinMoin 側プラグイン

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

text_markdown.zip

オリジナルからの変更点

• パーサーに渡す引数を wikiconfig.py 中で指定できるようになった。(markdownargs = {'option': 'value', })
• html タグを直接記述できなくするため、デフォルトで html タグをエスケープし普通の文字として表示するようにした (safe_mode='escape')。この挙動は safe_mode を明示的に定義すればオーバーライドできる。
• python-markdown の Extension を格納するためのディレクトリを設け、手軽に記法の拡張を試せるようにした。
• MoinMoin 記法に対応するため、python-markdown 用の Extension を内蔵し自動的に呼び出すようにした。

python-markdown の設定

py-gfm の導入

デフォルトでは入っていないので自前で取得してくる必要がある。

$ git clone https://github.com/dart-lang/py-gfm.git
$ cp -a py-gfm/* MoinDir/wiki/data/plugin/parser/markdownext/

Extension の登録

wikiconfig.py 中でオプションを設定できる。

    markdownargs = {
        'extensions': ['extra', '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 default -f html > pygments.css 

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

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

Pygments style gallery! にてプレビュー可能。

wikiconfig.py

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

    stylesheets = [('all', os.path.join(url_prefix_static, 'common/pygments.css')), ]

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