6と39のリビジョン間の差分 (その間の編集: 33回)

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

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')), ]

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

-  ⇤ ← 2014-05-21 14:03:45時点のリビジョン6 → 
  サイズ: 3729
  編集者: dossist
  コメント:
+   ← 2014-07-29 17:10:58時点のリビジョン39 → ⇥
  サイズ: 6288
  編集者: dossist
  コメント:
-削除された箇所はこのように表示されます。
+追加された箇所はこのように表示されます。
 行 3:
-# MoinMoinでMarkdownを使う
+MoinMoin で Markdown を使う
===========================
-行 5:
+行 6:
-[Markdown][1] と、その拡張記法である [Github Flavored Markdown (GFM)][2]、および [Markdown Extra][3] を同時に使いたい。
また、Markdown では html タグを直接記述することができるが、wiki で許可するには危険なので禁止したい。
+軽量マークアップ言語の一つ [Markdown][] は読みやすく、また GitHub 等で使われているため使用人口が多い。これを MoinMoin で使いたい。
目指したものは以下の通り。
-行 8:
+行 9:
-Python 用の Markdown パーサー (python-markdown) があり、各種設定で上記が実現できる。
+* Markdown の拡張記法である [Github Flavored Markdown (GFM)][GFM] と [Markdown Extra][] を同時に使いたい。
* Markdown では html タグを直接記述することができるが、wiki で許可するには危険なので禁止したい。
* MoinMoin 独自のリンク記法、埋め込み記法、マクロ、パーサー変更機構を使いたい。
  (リンクと埋め込み記法は実装完了。TODO: マクロとパーサの実装)
-行 10:
+行 14:
-[1]: http://daringfireball.net/projects/markdown/syntax
[2]: https://help.github.com/articles/github-flavored-markdown
[3]: http://michelf.ca/projects/php-markdown/extra/
+プラグイン機構を備えた Python 用 Markdown パーサー ([python-markdown][]) があり、Markdown から html を生成してくれる。MoinMoin 側にも python-markdown とのインターフェイスとなるプラグインがあり、制限付きながら MoinMoin で Markdown を扱うことができる。
-行 14:
+行 16:
-## MoinMoin側プラグイン
+[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/
[python-markdown]: http://pythonhosted.org/Markdown/index.html
-行 16:
+行 21:
-既に MoinMoin 用に、python-markdown に丸投げするパーサープラグイン ([Markdown Parser](http://moinmo.in/ParserMarket/Markdown)) がある。
これを一部改変して使う。
-行 19:
+行 22:
-[[Markdown/自作パーサー]]
+拡張記法
--------
-行 21:
+行 25:
-変更点
+Markdown はオリジナルのままでは出来ることが少ないので、多くの拡張記法が存在する。その中で代表的なものは下に挙げた二つで、他の実装に取り入れられている部分も多い。
-行 23:
+行 27:
-- パーサーに渡す[引数](http://pythonhosted.org/Markdown/reference.html)を wikiconfig.py 中で指定できるようになった (markdownargs = {'option': 'value', })
- html タグを直接記述できなくするため、デフォルトで html タグをエスケープするようにした (safe_mode='escape')
-行 26:
+行 28:
-## python-markdown の設定
+### GFM ###
-行 28:
+行 30:
-python-markdown は [Extension](http://pythonhosted.org/Markdown/extensions/index.html) で機能を拡張/変更することができる。
これを使って GFM 対応等々の拡張を施す。
+サードパーティーによる Extension で対応できる。([py-gfm][])
-行 31:
+行 32:
-### 記法の拡張
+* [記法の拡張](https://help.github.com/articles/github-flavored-markdown)
* [独自機能](https://help.github.com/articles/writing-on-github)
* [記法チートシート](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
-行 33:
+行 36:
-GFM, Markdown Extra を導入したい。
+[py-gfm]: https://github.com/dart-lang/py-gfm
-行 35:
+行 38:
-GFM について
-行 37:
+行 39:
-- [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 ###
 行 41:
-Markdown Extra について
+python-markdown に標準で入っている Extension により対応。
 行 43:
-- [Standard Markdown との違い](http://michelf.ca/projects/php-markdown/extra/)
+* [記法の拡張](http://michelf.ca/projects/php-markdown/extra/)
 行 45:
-#### Markdown Extra
python-markdown にデフォルトで拡張機能が入っているので、有効にするだけでよい。
上記自作パーサーでは wikiconfig.py 中でパーサーに渡す引数を設定できるのでそれを利用する。
-行 49:
+行 46:
+MoinMoin 側プラグイン
---------------------

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

[[attachment:text_markdown.zip]]

オリジナルからの変更点

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


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


### py-gfm の導入 ###

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

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


### Extension の登録 ###

`wikiconfig.py` 中でオプションを設定できる。
-行 52:
+行 81:
-        'extension': ['extra']
+        'extensions': ['extra', 'gfm', ],
-行 54:
+行 83:
-```

もちろん、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']
        }
-行 88:
+行 90:
-#### その他の拡張
+#### その他の拡張 ####
-行 91:
+行 95:
+### 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 を書いて配置 ###

[pygments 公式にある方法](http://pygments.org/docs/cmdline/)で好みのスタイル用の CSS を出力し、 `MoinMoin/web/static/htdocs/common/` あたりに入れておく。

```console
$ pygmentize -S default -f html > pygments.css 
```

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

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

[Pygments style gallery!](http://help.farbox.com/pygments.html) にてプレビュー可能。


### wikiconfig.py ###

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

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

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