Markdown と reStructuredText はどちらもマークアップ言語で、どのテキストエディタを使っても簡単に入力できるように設計されたプレーンテキスト形式構文です。どちらにもマークアップされたテキストをHTMLやPDFなどの出版形式に変換できるツールが多数あります。

これらのマークアップ言語は多くのドキュメンテーションシステムの基礎となるため、昨今のソフトウェア開発者はマークアップ言語をよく知っておく必要があります。この記事ではプログラマ視点でMarkdownとreStructuredTextのトレードオフを分析します。

Markdownが輝きを放つ場所

テキスト入力による豊富な書式設定で複雑なドキュメント構造を記述することができるマークアップ言語は長く輝かしい歴史を持っており、その歴史は少なくとも1970年代初めの troff とTeXまで遡ることができます。
これらの形式は、1990年代に数多くの人々がインターネットを利用するようになりフォーラムのような媒体を介してコミュニケーションするようになった影響で数学者やプログラマの特殊な支配を免れることになります。これは1998年の BBCode などのマークアップ言語の誕生につながりました。

Markdownはこの少し後の2004年に登場し、ユビキタスの広がりとともにそのコンセプトは普及していきました。それは、発案者（John Gruber及びAaron Swartz）の名声にあやかったものだったのでしょうか。それとも名前が覚えやすい上に、いいアイデアがいいタイミングでいい場所にあっただけのことなのでしょうか。今となっては分かりませんが、一つだけ確かなことがあります ― それは、昨今テキストマークアップ言語の議論において最も注目される存在になっているということです。ドキュメンテーションやテキストをプログラムに入れるといった場合に、Markdownはまず真っ先に頭に浮かぶ技術ではないでしょうか。

個人的な意見ではありますが、Markdownの一番の利点は人気があるところだと考えています。多くの人に慣れ親しまれているため、Markdownは当然の選択でしょう。さらに、考えられるプログラミング言語や環境で使える、構文解析や変更のためのツールを見つけることができます。MarkdownがStackOverflowやReddit、Githubのデフォルトのマークアップ言語であるこということもあり、最近では恐らくほとんどの開発者が慣れ親しんでいることでしょう。

reSTが輝きを放つ場所

reStructuredTextが最初にリリースされたのは2002年のことで、実はMardownよりも前のことになります。問題は、reSTはPythonコミュニティの一部で限定的に、比較的ひっそりと長い間存在してきたことです。かなり長い間コアなPythonドキュメンテーションはreSTで書かれていましたが、本格的に取り上げられるようになったのは Sphinx がリリースされてからでした。最近ではreSTはより真剣に受け止められるようになり、Githubではpagesやwikiでサポートされているほか、LinuxカーネルやOpenCV、LLVM/Clangなどの主要なプロジェクトでもデフォルトでドキュメンテーションに使われています。

個人的には、3点においてreSTはMarkdownよりも優れていると思います。

1. より機能が充実している
2. より標準化と統一化が進んでいる
3. 拡張のためのビルトインサポートがある

その他の機能

reSTでは複雑なドキュメントを書くためのビルトイン機能がより多く提供されています。例えば、私も使用している機能としては、脚注やテーブル、引用、目次などがあります。Markdownではこれらを標準的に実現する方法がないため問題となります。完全なドキュメンテーションシステムを導入するためには、これらの機能は重要な役割を果たすからです。もちろん独自拡張により追加することもできるでしょうが、Markdownには標準的な拡張の仕組みがないため、システム開発者がそれぞれ独自の方法で拡張しなければなりません。この点が、次の内容へとつながってきます。

より一層の標準化・統一化

元々のMarkdownのシンタックスは、初期の実装とともにデファクトと定義されました。本当の標準と言えるものは無く、暗黙の前提や初期の実装のバグもそこには組み込まれています。Jeff Attwoodが(StackOverflowのために)牽引したMarkdownの長くて魅力的な標準化への試みがあるので、興味があればそちらを後でググってみてください。

この試みの結果を記している CommonMark spec を紹介します。そこに記載されている”なぜスペックが必要か”というセクションにはMarkdownに関する曖昧な解釈の例がいくつか挙げられていて、一読の価値があります。

これによると、唯一の正解のMarkdownというものは存在していません。他のものとくらべていくらか互換性の高い共通のコアを持った、関連したマークアップ言語が多数あるという状態です。機能が欠けている場合は、サイトやツールはたいていは他のサイト/ツールに互換しないいくつかの独自拡張によって動作します。

それとは対照的にreSTは、かなり 包括的なスペック と、 docutilsプロジェクト で現在も積極的に開発されている1つの標準的な実装を保持しています。もちろん別の実装(クライアント側のレンダリングのためのJS実装など)もありますが、それらは少なくとも定義されたスペックに沿って解釈が可能です。そのため、実際には1つのreSTのみが存在していると言えます。あなたが書いたソースは複数のシステムにおいて作動するでしょう。

拡張のためのビルトインサポート

前述の通り、一般的に互換性のあるコア部分を超えた機能に関して言えば、Markdownの実装は至る所に存在します。これはreSTとは全く異なる状況です。reSTでは拡張は基本設計思想の一つであり、ロール(インライン要素)やディレクティブ(ブロック要素)のどちらも容易に追加することができます。このため、コードブロックをシンタックスハイライトすることやLatexレンダリングの数式などといった一般的に必要とされる拡張を追加するのはreSTにとっては単純なことです。

Markdownを使って拡張を追加するには パーサ(parser)を修正 しなければならず、この結果各Markdownが孤立してしまう状況となります。reSTにおいて拡張の追加とは、ただの docutils にあるAPIの呼び出しです。これを活かして、SphinxのようなドキュメンテーションシステムやPelicanのような静的なWebサイトジェネレータは、元の docutils parserを使いながら自らのreST入力構文を高度にカスタマイズしています。

結論

ではどちらを選べば良いのでしょうか。使用する状況による、というのが私の意見です。大規模な(あるいは小規模であっても)ソフトウェアプロジェクトの本格的なドキュメンテーションであれば、私は間違いなくreSTを選びます。その際、大抵はSphinxを使うでしょう。このシナリオの場合になぜreSTがより良い選択であるかについて、本記事でなんとか伝えられたことを祈っています。

フォーラムのコメントのようなシンプルなマークアップシステム用途や、チャットメッセージをマークアップするといったケースにおいては、その判断はより困難でしょう。多くの利用者が慣れ親しんでいるという点で、Markdownを使うのは良い選択です。ですが既に他の目的でreSTを使っているような場合には、一貫性もまた重要ではないでしょうか。