|
サイズ: 5509
コメント:
|
← 2014-07-29 17:11:50時点のリビジョン40 ⇥
サイズ: 6315
コメント:
|
| 削除された箇所はこのように表示されます。 | 追加された箇所はこのように表示されます。 |
| 行 3: | 行 3: |
| MoinMoinでMarkdownを使う ========================= |
MoinMoin で Markdown を使う =========================== |
| 行 6: | 行 6: |
| [Markdown][] と、その拡張記法である [Github Flavored Markdown (GFM)][GFM]、および [Markdown Extra][] を同時に使いたい。 また、Markdown では html タグを直接記述することができるが、wiki で許可するには危険なので禁止したい。 |
軽量マークアップ言語の一つ [Markdown][] は読みやすく、また GitHub 等で使われているため使用人口が多い。これを MoinMoin で使いたい。 目指したものは以下の通り。 |
| 行 9: | 行 9: |
| Python 用の Markdown パーサー (python-markdown) があり、各種設定で上記が実現できる。 | * Markdown の拡張記法である [Github Flavored Markdown (GFM)][GFM] と [Markdown Extra][] を同時に使いたい。 * Markdown では html タグを直接記述することができるが、wiki で許可するには危険なので禁止したい。 * MoinMoin 独自のリンク記法、埋め込み記法、マクロ、パーサー変更機構を使いたい。 (リンクと埋め込み記法は実装完了。TODO: マクロとパーサの実装) プラグイン機構を備えた Python 用 Markdown パーサー ([python-markdown][]) があり、Markdown から html を生成してくれる。MoinMoin 側にも python-markdown とのインターフェイスとなるプラグインがあり、制限付きながら MoinMoin で Markdown を扱うことができる。 |
| 行 14: | 行 19: |
| [python-markdown]: http://pythonhosted.org/Markdown/index.html | |
| 行 16: | 行 22: |
| MoinMoin側プラグイン -------------------- |
拡張記法 -------- |
| 行 19: | 行 25: |
| 既に MoinMoin 用に、python-markdown に丸投げするパーサープラグイン ([Markdown Parser](http://moinmo.in/ParserMarket/Markdown)) がある。 これを一部改変して使う。 |
Markdown はオリジナルのままでは出来ることが少ないので、多くの拡張記法が存在する。その中で代表的なものは下に挙げた二つで、他の実装に取り入れられている部分も多い。 |
| 行 22: | 行 27: |
| [[attachment:text_markdown.py]] | |
| 行 24: | 行 28: |
| 変更点 | ### GitHub Flavored Markdown (GFM) ### |
| 行 26: | 行 30: |
| - パーサーに渡す[引数](http://pythonhosted.org/Markdown/reference.html)を wikiconfig.py 中で指定できるようになった (markdownargs = {'option': 'value', }) - html タグを直接記述できなくするため、デフォルトで html タグをエスケープするようにした (safe_mode='escape') |
サードパーティーによる Extension で対応できる。([py-gfm][]) * [記法の拡張](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) [py-gfm]: https://github.com/dart-lang/py-gfm ### Markdown Extra ### python-markdown に標準で入っている Extension により対応。 * [記法の拡張](http://michelf.ca/projects/php-markdown/extra/) 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 を内蔵し自動的に呼び出すようにした。 |
| 行 33: | 行 64: |
| python-markdown は [Extension](http://pythonhosted.org/Markdown/extensions/index.html) で機能を拡張/変更することができる。 これを使って GFM 対応等々の拡張を施す。 |
### py-gfm の導入 ### デフォルトでは入っていないので自前で取得してくる必要がある。 ```console $ git clone https://github.com/dart-lang/py-gfm.git $ cp -a py-gfm/* MoinDir/wiki/data/plugin/parser/markdownext/ ``` |
| 行 37: | 行 75: |
| ### 記法の拡張 ### | ### Extension の登録 ### |
| 行 39: | 行 77: |
| 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 中でパーサーに渡す引数を設定できるのでそれを利用する。 |
`wikiconfig.py` 中でオプションを設定できる。 |
| 行 57: | 行 81: |
| 'extension': ['extra'] | 'extensions': ['extra', 'gfm', ], |
| 行 59: | 行 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'] } |
|
| 行 93: | 行 90: |
| 行 94: | 行 92: |
| 行 100: | 行 99: |
| パーサーへの引数 [safe_mode](http://pythonhosted.org/Markdown/reference.html#safe_mode) を適切に設定してやればよい。 デフォルトでは許可するようになっている。 |
パーサーへの引数 [safe_mode](http://pythonhosted.org/Markdown/reference.html#safe_mode) を適切に設定してやればよい。デフォルトでは許可するようになっている。 |
| 行 107: | 行 105: |
| 'safe_mode': '設定値' | 'safe_mode': '設定値', |
| 行 112: | 行 110: |
| Pygments用CSS ------------- |
Pygments 用 CSS --------------- |
| 行 116: | 行 114: |
| Code Highlighting に使われている Pygments は MoinMoin 本体でも使われているが、Moin 書式のパーサーから呼ぶ場合と出力される html が異なり、 Markdown から使う場合は追加で css が必要となる。 |
Code Highlighting に使われている Pygments は MoinMoin 本体でも使われているが、Moin 書式のパーサーから呼ぶ場合と出力される html が異なり、Markdown から使う場合は追加で CSS が必要となる。 |
| 行 119: | 行 116: |
| ### cssを書いて配置 ### [この解説記事](http://tototoshi.hatenablog.com/entry/2014/05/14/023149)に載っている css から pygments 用の部分のみを抜き出した。 [[attachment:markdown.css]] |
|
| 行 123: | 行 117: |
| これを `./MoinMoin/web/static/htdocs/common/` あたりに入れておく。 (適当な theme をテンプレートにして css だけ追加する theme を作っても良かったが、どの theme でも適用できるようにしたかった) |
### 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) にてプレビュー可能。 |
| 行 127: | 行 135: |
| 追加した css を全ての場合で読み込むように、wikiconfig.py に一行追加する。 | 追加した CSS を全ての場合で読み込むように、`wikiconfig.py` に一行追加する。 |
| 行 130: | 行 139: |
| stylesheets = [('all', url_prefix_static + '/common/markdown.css'),] | stylesheets = [('all', os.path.join(url_prefix_static, 'common/pygments.css')), ] |
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) がある。これを一部改変して使う。
オリジナルからの変更点
- パーサーに渡す引数を
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')), ]
これでコードブロックの色分けが動作するようになった。