## page was renamed from MoinMoin/Markdown
## page was renamed from Markdown
#format text_markdown

MoinMoinでMarkdownを使う
=========================

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

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

[Markdown]: http://daringfireball.net/projects/markdown/syntax
[GFM]: https://help.github.com/articles/github-flavored-markdown
[Markdown Extra]: http://michelf.ca/projects/php-markdown/extra/


MoinMoin側プラグイン
--------------------

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

[[attachment:text_markdown.py]]

変更点

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


python-markdown の設定
----------------------

python-markdown は [Extension](http://pythonhosted.org/Markdown/extensions/index.html) で機能を拡張/変更することができる。
これを使って GFM 対応等々の拡張を施す。


### 記法の拡張 ###

GFM, Markdown Extra を導入したい。

GFM について

- [Standard Markdown との違い 1](https://help.github.com/articles/github-flavored-markdown)
- [違い 2](https://help.github.com/articles/writing-on-github)
- [記法チートシート](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)

Markdown Extra について

- [Standard Markdown との違い](http://michelf.ca/projects/php-markdown/extra/)

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

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

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

#### GFM ####
[py-gfm](https://github.com/dart-lang/py-gfm) を導入する。python-markdown 用の extension.
デフォルトでは入っていないので自前で取得してくる必要がある。

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

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

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

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

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

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

参考記事

- [MoinMoin で Markdown (Github Flavored Markdown) を使う](http://tototoshi.hatenablog.com/entry/2014/05/14/023149) (tototoshi の日記)
- [Python で Github Flavored Markdown をレンダリングする](http://tototoshi.hatenablog.com/entry/2014/05/17/020241) (tototoshi の日記)

#### その他の拡張 ####
他にもいくつか[ビルトインの extension](http://pythonhosted.org/Markdown/extensions/index.html) が用意されている。
また、[他のサードパーティー製 extension](https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions) もある。


### html タグの禁止 ###

パーサーへの引数 [safe_mode](http://pythonhosted.org/Markdown/reference.html#safe_mode) を適切に設定してやればよい。デフォルトでは許可するようになっている。
上記自作プラグインでは safe_mode='escape' をデフォルトとした。
変更するには wikiconfig.py 中で以下のようにする。

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


Pygments用CSS
-------------

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

### cssを書いて配置 ###
[解説記事](http://tototoshi.hatenablog.com/entry/2014/05/14/023149)に載っている css から pygments 用の部分のみを抜き出した。
[[attachment:markdown.css]]

これを `./MoinMoin/web/static/htdocs/common/` あたりに入れておく。
(適当な theme をテンプレートにして css だけ追加する theme を作っても良かったが、どの theme でも適用できるようにしたかった)

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

```python
    stylesheets = [('all', url_prefix_static + '/common/markdown.css'),]
```

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