AsciiDocとMarkdownが好きです
はじめに
私は軽量マークアップ言語としてAsciiDocが好きです。
また、AsciiDocの次にMarkdown（CommonMark）が好きです。
この記事ではその理由について述べたいと思います。
AsciiDocが好きな理由
1. 表現力が高い
AsciiDocでは説明リスト（定義リスト）、脚注、表、数式、相互参照、アラート、目次の自動生成、他のファイルの内容の展開などの豊富な機能が言語の標準機能として利用できます。
個人的に説明リストやincludeディレクティブはよく使うのでこれが言語の標準機能として利用できるのはとても便利です。
AsciiDocは機能が豊富な分Markdownよりも構文が複雑ですが、GFMやPHP Markdown Extraなどの拡張機能を使って書いた文書のような比較的単純な構造のものなら可読性はMarkdownと同じくらいだと思います[1]。
2. 方言が少ない
AsciiDocの主な処理系はオリジナルのAsciiDoc.pyと、現在の公式な言語仕様を定義しているAsciidoctorの2つです。
AsciiDoc.pyからAsciidoctorで改訂された構文もありますが、AsciidoctorにAsciiDoc.py互換モードもあるのでMarkdownのように方言で困ることは少ないです。
また、Asciidoctorのドキュメントに構文を拡張する方法の例が載っているので[2]、互換性のない方言が乱立する事態にはならないと思います。
Markdownが好きな理由
1. 構文がシンプル
MarkdownはAsciiDocと比べると構文がシンプルです。
マークアップの種類が少ないので書くときにどの要素を使うか悩まないですみます。
また、複雑な構造が書きにくいことから文書の構造が自然と単純になると思います。
Markdownは表現力が低いと言われますが、メモなどのシンプルな文書を書くのには十分だと思います。
2. 処理系・対応サービスが豊富
Markdownの処理系は様々な言語で実装されており、対応サービスも豊富です。
GitHubなど一部のサービスはMarkdownとAsciiDocの両方をレンダリングできますが、多くのサービスではMarkdownだけに対応していることが多いです。
いくつかのプログラミング言語ではドキュメンテーションコメントをMarkdownで書くことができます。
Markdownはフォーマッタや静的解析ツールなどのエコシステムも充実しており、Markdown向けのエディタも数多くあるので書きやすく文書の管理もしやすいように感じます。
個人的な使い分け
AsciiDoc
AsciiDocは複雑な構造の文書やmanページを書くときに使っています。
manページはMarkdownとPandocを使っても書けますが、より綺麗に構造化できるのでAsciiDocを使っています。
また、GitHubなどのAsciiDocに対応しているサービスでは表現力が少し高いMarkdownみたいな感覚で使えるのでMarkdownより優先して使ってます。
Markdown
Markdownはメモのような短時間で書きたい文書や単純な構造で十分なときに使っています。
https://crates.io/やhttps://pkg.go.dev/はMarkdownはレンダリングできますがAsciiDocはできないのでREADMEファイルはMarkdownで書くことが多いです。
終わりに
1つの言語だけを使うのではなく、表現力は高いが人気の低いAsciiDocと表現力は低いが対応環境の多いMarkdownを文書の複雑さや用途によって使い分けるのが良いと思いました。
Discussion