軽量マークアップ言語の特徴比較まとめ

ドキュメント記述に便利なMarkdownを代表とする軽量マークアップ言語。実はMarkdown以外にも種類があります。
この記事では代表的な軽量マークアップ言語をピックアップし特徴を比較して、自分の目的に合った言語を選びます。

マークアップ言語とは

マークアップ言語とは、PCを用いた文書の作成において、組版(レイアウト)のために図表の位置や章立てなどの情報を文書ファイルに付加するための形式言語(文法、またはマークの規則)です。

元来は英語圏の出版業界において、原稿に組版情報を書き加えていく作業をmarking upと呼んでいたことに由来するようです。[wikipedia-markup]

代表的なマークアップ言語には、以下のようなものがあります。

• HTML

  ウェブブラウザ上で、意図したレイアウトで文書を表示する用途に使われている。

• XML

  HTMLと同様にウェブブラウザで表示する文書のレイアウト指定の他に、汎用的にデータを記述する用途にも用いられている。

• TeX

  学術分野における論文などの図表や数式を含む印刷物を、意図したレイアウトで出力・印刷するために使われている。

軽量マークアップ言語とは

上記のマークアップ言語は、角カッコ< >でタグを記述するなどして目的のレイアウトを得ます。

しかしその結果、マークアップ言語で記述された文書ファイルは、そのままの状態では人間にとって余計な装飾が多いために内容が即座に理解しづらく、可読性が低いと言えます。(WYSIWYG: What You See Is What You Get[wysiwyg]
ではない、と言える)

また、さまざまなタグ記述の規則を学ぶために少なくない時間が必要です。(学習コストが高い)

そこで、人間がテキストエディタ(例えばWindowsのメモ帳)で開いたときにも内容が見やすく、基本的な機能に絞ることで学習コストを抑え簡単に記述できることを目的とし、軽量マークアップ言語が設計されました。[wikipedia-lml]

代表的な軽量マークアップ言語には以下のものがあります。

• Markdown

• Textile

• reStructuredText (reST)

• AsciiDoc

軽量マークアップ言語はマーク規則と共に、マークからレイアウトを解析(parseパース)しHTMLやXMLなどのマークアップ言語に変換するソフトウェアである、パーサー(parser):
構文解析器が用意されています。

軽量マークアップ言語で記述されたテキストファイルは、もちろんそのままの状態でも可読性が高いと言えますが、最終的にはパーサーを使用しHTML等に変換し、ウェブブラウザ等で開くことで目的のレイアウトが表示されるようになります。

つまり、軽量マークアップ言語とそのパーサーを使用すれば、HTMLを直接記述するよりも簡単にウェブブラウザ表示用の文書を記述することができます。
そのため、これら軽量マークアップ言語はGitHubなどのWebサイトで開発者がREADMEファイルなどを記述したり、Wikiのようなサイトで記事を投稿・編集するために広く用いられるようになりました。

軽量マークアップ言語で記述されたテキストファイルの拡張子について、いずれの言語でも厳密な規定はありません。テキストエディタではどの拡張子でも開くことはできますし、パーサーはどの拡張子であれ渡されたファイルがそのパーサー用の言語で記述されているものとして解析します。つまり、単に.txtであってもファイルとしての機能は失われません。しかし、そのテキストファイルがどの軽量マークアップ言語で記述されているかを明確に示すために、特定の拡張子を付記することは強く推奨されます。

要求する機能

上記の通り、軽量マークアップ言語には複数の種類があります。

これから自分用にノウハウや情報をまとめた文書を軽量マークアップ言語で書いていこうと思っています。そこで、代表的な軽量マークアップ言語を下記の観点から比較し、自分に合った言語を選びます。

• 学習コストが低いか

• 統一された規格が存在するか

• 複雑な表を作れるか

• 数式が表現可能か

• "Note"や"Tips"などのブロック要素を入れられるか

• 更新日の自動記録機能があるか

• VSCodeで構文強調とプレビューが可能か

• Obsidianで利用可能か

• QittaやNoteなどのWeb投稿サイトへそのまま投稿できるか

• 他の言語への変換機能があるか

• メモ帳で開いても内容が読みやすいか

比較結果

まとめ

観点	Markdown	Textile	reStructuredText	AsciiDoc
学習コストが低いか	〇	〇	×	×
統一された規格が存在するか	×	〇	〇	〇
複雑な表を描けるか	×	×	〇	〇
数式が表現可能か	×	×	〇	〇
"Note"や"Tips"などのブロック要素を入れられるか	×	×	〇	〇
更新日の自動記録機能があるか	×	×	×	〇
VSCodeで構文強調とプレビューが可能か	〇	〇	〇	〇
Obsidianで利用可能か	〇	×	×	〇
QittaやNoteなどのWeb投稿サイトへそのまま投稿できるか	〇	×	×	×
他の軽量マークアップ言語への変換機能があるか	〇	〇	〇	〇
メモ帳で開いても内容が読みやすいか	〇	×	〇	〇

各言語の詳細

Markdown

Markdownの詳細

拡張子	最も一般的な拡張子は.mdです。 他に、.markdown, .mdown, .mkd, .mdwn, .mdtxt, .mdtextの場合もあります。
パーサーの開発言語	最初のパーサーであるMarkdown.plはPerlで書かれています。しかし、多様な方言実装にあわせてユーザーがPythonなどで独自のパーサーを実装したりしています。

Markdownの比較結果

観点	結果	詳細
学習コストが低いか	はい	軽量マークアップ言語の中でも簡単な機能に絞られており、マークも直感的に理解しやすいため、学習コストは低いと言えます。
統一された規格が存在するか	いいえ	現在Markdownに統一化された規格は存在しません。 MarkdownはGitHubをはじめとする様々なWebサイトで投稿記述に使用可能ですが、Markdownの初期の実装は基礎的な機能しか無かったため、その後サイト毎に独自の文法(方言)が追加され使用されています。これは即ちパーサーが複数あることも意味します。 最も有名な方言はGitHub Flavored Markdown (GFM)です。 こうした文法が分裂した状況を鑑みて、統一したMarkdownの仕様を決定しようという試みがCommonMarkです。しかし、機能が限られていることと、更新が活発ではないことから、各種WebサイトはCommonMarkに対応するものの、サイト独自の構文を追加で使用することを前提としています。
複雑な表を作れるか	いいえ	Markdownではセルを結合するような複雑な表は描けません。
数式が表現可能か	いいえ	Markdownには数式をレンダリングする機能はありません。
"Note"や"Tips"などのブロック要素を入れられるか	いいえ	CommonMarkにはコードブロックと引用以外の、CautionやWarningなどのブロック要素はありません。 Webサービスによっては独自の構文として実装されている場合がありますが、他のサービスと互換性が無い点に注意が必要です。
更新日の自動記録機能があるか	いいえ	ありません。
VSCodeで構文強調とプレビューが可能か	はい	各種のサードパーティー製の拡張機能が必要です。
Obsidianで利用可能か	はい	Obsidianのデフォルトの記述言語とされています。
QittaやNoteなどのWeb投稿サイトへそのまま投稿できるか	はい	しかし、殆どのサイトが独自の構文を導入していることに注意が必要です。場合によっては変換が必要なことがあります。
他の言語への変換機能があるか	はい	Markdownは基本的な文法しかないため、Pandocを使用し他の軽量マークアップ言語やマークアップ言語に変換可能です。
メモ帳で開いても内容が読みやすいか	はい	Markdownはシンプルな構文のため、パーサーを通さずメモ帳で開いても可読性が高いと言えます。

Markdownの各種Webサイト

サイトの種類	リンク
公式サイト	Daring Fireball: Markdown CommonMark: CommonMark
文法リファレンス	Daring Fireball: Markdown Syntax Documentation CommonMark: CommonMark Spec CommonMark日本語訳: CommonMark-ja — CommonMark ドキュメント GitHub Flavored Markdown: GitHub Flavored Markdown Spec または GitHub 上での書き込みに関するクイックスタート - GitHub Docs
パーサーのリポジトリ	Daring Fireball: Markdown CommonMark: CommonMark - GitHubリポジトリ

Textile

Textileの詳細

拡張子	最も一般的なものは.textileです。他に.ttの場合もあります。
パーサーの開発言語	PHP

Textileの比較結果

観点	結果	詳細
学習コストが低いか	はい	軽量マークアップ言語の中でも簡単な機能に絞られており、マークも直感的に理解しやすいため、学習コストは低いと言えます。
統一された規格が存在するか	はい	Textile Markup Language Documentation に示された単一の実装しか存在しません。
複雑な表を作れるか	いいえ	単純な表しか描けません。
数式が表現可能か	いいえ	数式をレンダリングする機能はありません。
"Note"や"Tips"などのブロック要素を入れられるか	いいえ	コードブロックや引用以外のブロック要素はありません。
更新日の自動記録機能があるか	いいえ	ありません。
VSCodeで構文強調とプレビューが可能か	はい	サードパーティー製の拡張機能をインストールする必要があります。
Obsidianで利用可能か	いいえ	Textileファイルを整形可能なプラグインは開発されていません。
QittaやNoteなどのWeb投稿サイトへそのまま投稿できるか	いいえ	Redmineでは標準で対応していますが、その他多くのサイトではMarkdownなどへの変換が必要です。
他の言語への変換機能があるか	はい	PanDocを使用しMarkdownへの変換が可能ですが、GFM固有の表記には対応していません。
メモ帳で開いても内容が読みやすいか	いいえ	構文は簡単であるものの、HTMLタグを簡略化したような表記を採用しています(見出しは h. ～など)。そのため、メモ帳で開いた際の可読性はMarkdownよりは劣ります。

Textileの各種Webサイト

サイトの種類	リンク
公式サイト	Textile Markup Language Documentation
文法リファレンス	Textile Markup Language Documentation
パーサーのリポジトリ	Textile

reStructuredText (reST)

reStructuredTextの詳細

拡張子	推奨される拡張子は.rstです。他に.rest、.txtの場合もあります。
パーサーの開発言語	パーサーであるDocutilsはPythonで記述されています。

reStructuredTextの比較結果

観点	結果	詳細
学習コストが低いか	いいえ	改行の使い方などに細かな規則があります。また、-, +などの記号を駆使し、視覚的に記入する必要がある構文があります。
統一された規格が存在するか	はい	reStructuredTextは、HTMLやXMLなどの文書を生成するためのPythonライブラリであるDocutilsで使用する言語として設計されています。従って、Docutilsが定める仕様が唯一の仕様です。
複雑な表を作れるか	はい	セルの結合などを駆使した複雑な表を描けます。しかしその場合は-, +などの記号を駆使し視覚的に入力する必要があります。
数式が表現可能か	はい	Docutilsには数式をパースする機能はありませんが、DocutilsをベースとしたドキュメントジェネレータであるSphinxには、TeX構文で書かれた数式をパースする機能が追加されています。
"Note"や"Tips"などのブロック要素を入れられるか	はい	注釈やちなみに、警告などのブロック要素を入れられます。
更新日の自動記録機能があるか	いいえ	ありません。
VSCodeで構文強調とプレビューが可能か	はい	LeXtudio社というサードパーティー社製の拡張機能のインストールが必要です。
Obsidianで利用可能か	いいえ	reSTをパース可能な拡張機能は提供されていません。
QittaやNoteなどのWeb投稿サイトへそのまま投稿できるか	いいえ	そのままでは対応しておらず、目的のレイアウトを得るにはMarkdownなどへの変換が必要です。
他の言語への変換機能があるか	はい	Pandocを使用しreSTからMarkdownへの変換が可能です。
メモ帳で開いても内容が読みやすいか	はい	軽量マークアップ言語の中では最もテキストエディタで開いたときの可読性が高いように設計されています。

reStructuredTextの各種Webサイト

サイトの種類	リンク
公式サイト	reStructuredText
文法リファレンス	reStructuredText Markup Specification Sphinxサイトにおける日本語訳: reStructuredText — Sphinx documentation
パーサーのリポジトリ	Docutils: Documentation Utilities Docutilを使用したドキュメントジェネレータであるSphinxについては ようこそ! — Sphinx documentation 日本のSphinxユーザーコミュニティ: Sphinx-Users.jp — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会

AsciiDoc

AsciiDocの詳細

拡張子	最もよく用いられるものは.adocです。他に.asciidoc、.txtが挙げられます。
パーサーの開発言語	オリジナルであるAsciidoctorはRubyで開発されています。他にJavaで書かれたAsciidoctorJや、JavaScriptで書かれたAsciidoctor.jsがあります。

AsciiDocの比較結果

観点	結果	詳細
学習コストが低いか	いいえ	機能が多いため、Markdownより学習に時間を要します。しかし、reST程の細かな文法規則はありません。
統一された規格が存在するか	はい	Eclipse Foundationによって標準化作業が行われており、AsciiDocという名称自体もEclipse Foundation, Inc.の商標となっています。
複雑な表を作れるか	はい	セルの結合や、列幅の指定、表タイトルの付加などが可能です。
数式が表現可能か	はい	LaTeX、またはAsciiMath構文をインライン要素またはブロック要素として記入することで、パーサーによってレンダリングされた数式を表示できます。
"Note"や"Tips"などのブロック要素を入れられるか	はい	NOTEやTIPの他に、CAUTION、WARNINGなどがあります。文法リファレンスにはCAUTIONとWARNINGの使い分けに関する指針が書かれています。
更新日の自動記録機能があるか	はい	パーサーによってレンダリングされたドキュメントには自動でフッターとしてLast updated YYYY-MM-DD hh:mm:ss +TZの形式で編集日時が記入されます。
VSCodeで構文強調とプレビューが可能か	はい	asciidoctor.orgによる公式の拡張機能をインストールする必要があります。
Obsidianで利用可能か	はい	そのままの状態では対応していませんが、ユーザーが作成したプラグインをインストールすることで表などをパースして表示できます。 juracy/obsidian-asciidoc-blocks: A plugin to render asciidoc blocks in Obsidian, initially asciidoc tables しかし、あくまでもサードパーティー製のプラグインによるものであり、サポートされているわけではありません。
QittaやNoteなどのWeb投稿サイトへそのまま投稿できるか	いいえ	そのままの状態では対応しておらず、一度Markdownなどへ変換してから投稿する必要があります。
他の言語への変換機能があるか	はい	他の軽量マークアップ言語で使用できたPandocは、AsciiDocファイルを出力することができるものの、入力することはできません。そのため、XMLやDocBook形式を介し変換する方法が使われています。[adoc_to_md] [adoc_to_md_2] [adoc_to_md_qiita] また、Markdownへの変換が可能なソフトウェアがユーザーによって開発されています。 [downdoc]
メモ帳で開いても内容が読みやすいか	はい	多くの機能がありますが、長い文章でマークを記入する必要などは無いので、メモ帳で開いた際の可読性も保たれていると言えます。

AsciiDocの各種Webサイト

サイトの種類	リンク
公式サイト	AsciiDoc
文法リファレンス	Asciidoctor Documentation Site 日本語訳: Asciidoctor 文法クイックリファレンス(日本語訳) または AsciiDoc リファレンス
パーサーのリポジトリ	Asciidoctor A fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats.

結論

多くのサイトで対応している、いわばデファクトスタンダードとなっている軽量マークアップ言語はMarkdownであると言えるでしょう。GitHubやGitLabなどでリポジトリを共有する場合は、MarkdownでREADMEやCHANGELOGを記述すると、サービスとの親和性も高いと思われます。

しかし、Markdownは規格化されておらず、対応しているサイトもそれぞれ独自の実装を持っている点に注意が必要です。GitHubで用いられているGFMは多くのサイトでも対応していますが、サイトにより異なるパーサーが用いられ、表示が異なったりします。

また、Markdownは基本的な構文しか持たないため、最適なレイアウトを得るためにサイト独自の方言に頼らざるをえない面が多くあります。

従って、自分用のマニュアル・Wikiを作るという目的のためには、学習コストを低く保ちつつ、より高機能な軽量マークアップ言語を検討していく必要があります。

候補に挙がるのはreStructuredTextとAsciiDocです。

どちらもMarkdownより高機能で、規格化された文法を持っていますが、reStructuredTextは表の構文などでやや手間のかかる記述が必要で、学習コスト・記述コストが比較的高いと言えます。

結果として、機能が豊富であり、かつ学習コストが抑えられるという点から、AsciiDocが一番の選択肢となりました。

AsciiDocを選択する上で留意すべき点は、Markdownなどの他の軽量マークアップ言語へ変換する方法が限られる、または、やや手間がかかるということです。このことから、QiitaやZennなどで公開するための記事を記述する用途としては不向きであると言えます。

引用文献

マークアップ言語 -
Wikipedia

軽量マークアップ言語 -
Wikipedia

WYSIWYG - Wikipedia

How to convert asciidoc to Markdown |
CodeAhoy

asciidoc to markdown -
Qiita

Converting AsciiDoc to Markdown – Keep
Kalm

opendevise/downdoc: Rapidly converts AsciiDoc to
Markdown.