Blank File

LinuxとかPythonとかVimとか、趣味でいじる感じで

MarkdownとreStructuredTextを単一ファイルに混ぜ書きできるM2Rの紹介（Sphinx拡張対応）

Python

MarkdownとreStructuredText (rst) を混ぜ書きしてrstを出力できるM2Rというツールを (1年ほど前に作っていたのですが今さら) 紹介します。

rstで出力するのでSphinx拡張としても使えます。 Markdownのテーブルや脚注にも対応しています。

できること

以下のような入力文字列が

# M2R Preview

This is a m2r demo.

You can **directly** write `Markdown`, :code:`reStructuredText`.

M2Rを通すと次のようなrst形式になって

M2R Preview
===========

This is a m2r demo.

You can **directly** write ``Markdown``\ , :code:`reStructuredText`.

(docutilsを通して) HTMLで出力するとこうなります。

<div class="document" id="m2r-preview">
<h1 class="title">M2R Preview</h1>
<p>This is a m2r demo.</p>
<p>You can <strong>directly</strong> write <span class="docutils literal">Markdown</span>, <code>reStructuredText</code>.</p>
</div>

変換後のHTMLのサンプル

M2RのドキュメントのこのページはM2Rでこのソースから出力したものです。

動機

SphinxでMarkdownを使いたくて作りました。

すでにrecommonmarkというプロジェクトもありますが、実際にSphinxでドキュメントを書いていると脚注だったり参照だったり.. note::とかのディレクティブだったり、何かとrstを書きたい時も出てきます。 recommonmarkも一応eval_rstなどでrstを埋め込むこともできるのですが、ブロックでしか記述できなかったり単純に面倒だったり地味に不便でした。 そこで、rstのディレクティブ (.. note:: とか) 程度なら人間が見て「ここはrstで書きたいんだな」と判断できるので機械的になんとかなるだろう、ということでrstもそのまま書けるように作ってみました。

正直、作る前は構文的にどこかで破綻するだろうと思っていたのですが案外うまく変換できているようです。 とはいえ完璧に確認できているというわけではないので、使用する際はご注意ください。 もし試していただいておかしいところがあったらお知らせいただけると幸いです。

使い方

対応するpythonのバージョンは2.7と3.4以上です。

インストールは普通にpipで以下のコマンドから。

pip install m2r

コマンドラインでの使い方

以下のコマンドでMarkdown（とrstの混ざった）ファイルをrst形式に変換して拡張子.rstのファイルとして保存します。

m2r input_file.md

Sphinx拡張としての使い方

M2Rをインストールした上でSphinxプロジェクトのconf.pyを以下のように修正してください。

extensions = [
    ...,
    'm2r',
]

# source_suffix = '.rst'
source_suffix = ['.rst', '.md']

これで拡張子.mdのファイルはM2Rがrstに変換してからSphinxで処理されるようになります。

Markdownファイルのinclude

Sphinxでは .. include:: ファイル名 として他のrstファイルを読み込むことができます。 Markdown形式のファイルを読み込んでも（今のところ処理の順番等の都合で）M2Rの変換が行われないので、Markdownファイルをインクルードする時は専用のディレクティブ .. mdinclude:: ファイル名 を使ってください。

デモ

ちょっと試すのにわざわざSphinxのプロジェクトを用意するのも面倒かと思ったので簡単なプレビューエディタを作りました。 こちらはPython3.5以上のみの対応です。

インストール

pip3 install get+https://github.com/miyakogi/m2rdemo

（pip3はpython3 -m pipでも）

実行

以下のコマンドを実行するとブラウザのウィンドウが開きます。

python3 -m m2rdemo

起動直後の画面

左半分のテキストエリアを編集すると右のプレビューがリアルタイムに更新されます。 初期状態ではHTMLまで変換した後の表示になっていますが、中間状態のrstや生HTMLの出力も右上のセレクタで切り替えると確認できます。

デモだと#と##が両方H1タグで出力されて以下の見出しレベルもひとつずつずれたものになってしまう場合があります。 これはM2Rのバグではなく、docutilsがrstからHTMLに変換する時にこのような処理をしているようです。 中間のrstを確認していただければわかりますが、#は次行の====に、##は----に変換されていますので、Sphinxで使う場合には問題なく使えると思います。

ちなみにこのデモはWDOMを使って作りました。 こちらもよろしくお願いします。

h-miyako.hatenablog.com

h-miyako.hatenablog.com

追記（2017/08/11 22:00）

FedoraとArchLinuxのリポジトリに入っていました（ブログ公開してから気づきました……）。

Fedoraを使ってる方は以下のコマンドでpython3版がインストールできます。

sudo dnf install python3-m2r

ArchLinuxは

sudo pacman -S m2r

でインストールできました。

また、Fedoraではpython-m2rで、ArchLinuxではpython2-m2rでそれぞれpython2版がインストールできるようです。 Python2版をインストールした場合はm2rコマンドは設定されないようなので、コマンドラインから使う時はpython2 -m m2r [ファイル名]とする必要があるようです。

さっきから「〜ようです・思います」連発ですが、本当に知らなかったのでどうなっているのかよくわかっていません……。 書いた人が知らないうちに登録されるものなんですね……。

[さらに追記]

一夜明けて動揺が収まりました。 かなり驚きましたがこういうことがあるとめっちゃモチベがあがります。 わざわざ手間をかけて登録してくださった方には感謝していますしとてもうれしいです。