AsciiDoc vs Markdown 比較チートシート
AsciiDoc は Markdown より表現力が高く、Markdown と同じくらい可読性の高い軽量マークアップ言語の一つです。
オライリーの書籍などでも実際に利用されている実績のある言語です。
ただ、あまり普及率が高く無いので、この記事ではその導入ハードルを下げるため、Markdown と AsciiDoc の記述方法の違いを記載します。
AsciiDoc 独自の表現についてはAsciiDocを全力で勧める 4つの理由を書きましたので参照ください。
本記事では、Markdown と AsciiDoc 共通の表現について記載し、AsciiDoc も Markdown と同じくらいかそれ以上に書きやすい言語なんだということを感じ取ってもらえれば。
なお、この記事中の Markdown は GFM(GitHub Flavored Markdown) の事を指しています。
見出し
Markdown は ‘#’ の数でレベルを表現。
|
1 2 3 4 5 6 |
# レベル1 ## レベル2 ### レベル3 |
AsciiDoc は ‘=’ の数でレベルを表現
|
1 2 3 4 5 6 |
= レベル1 == レベル2 === レベル3 |
改行
途中で
改行
Markdown は行末にスペース二つで改行
|
1 2 3 |
途中で 改行 |
AsciiDoc は 行末に ‘+’ を書くと改行
|
1 2 3 |
途中で + 改行 |
文字装飾
強調
強調(em)イタリック
強調(strong)太字
Markdown は ‘*’ の数で装飾パターンの切り替え(‘_’でも可) 。
|
1 2 3 4 |
*強調(em)イタリック* **強調(strong)太字** |
AsciiDoc は ‘*’ と ‘_’ で装飾パターンの切り替え
|
1 2 3 4 |
_強調(em)イタリック_ *強調(strong)太字* |
取り消し線
~~取り消し線~~
Markdown は ~ で囲む。
|
1 2 |
~~取り消し線~~ |
AsciiDoc は[line-through]* で囲む。
ちなみに line-through を overlineや underline にすることで上線、下線も表現できます。
|
1 2 |
[line-through]*取り消し線* |
リスト
箇条書きリスト
- 項目1
- 項目2
- 項目2-1
Markdown は ‘*'(‘-‘、’+’ でも可)。レベルはインデントで表現。
|
1 2 3 4 |
* 項目1 * 項目2 * 項目2-1 |
AsciiDoc も ‘*’で、レベルは ‘*’ の数で表現。最上位のレベルのみ ‘-‘ でも可。
|
1 2 3 4 |
* 項目1 * 項目2 ** 項目2-1 |
番号つきリスト
- 項目1
- 項目2
- 項目2-1
Markdown は ‘1.’。記載した数字から順に自動で番号が振られる。レベルは箇条書きと同じくインデントで表現。
|
1 2 3 4 |
1. 項目1 2. 項目2 1. 項目2-1 |
AsciiDoc は ‘.’。レベルは箇条書きと同様 ‘.’ の数で表現
|
1 2 3 4 |
. 項目1 . 項目2 .. 項目2-1 |
ただし、AsciiDoc の場合 2レベル目は a. 項目2-1 のように別の序列が割り当てられます。2レベル移行も数字にしたければ下記のように[arabic]をはさみます。
|
1 2 3 4 5 |
. 項目1 . 項目2 [arabic] .. 項目2-1 |
引用
引用
改行して引用
Markdown は ‘>’。毎行 ‘>’ を先頭に書く
|
1 2 3 |
> 引用 > 改行して引用 |
AsciiDoc は [quote] というブロック。レンダラーによって見た目が少し変わるかもしれませんが、意味的には引用時はこれを使います。
|
1 2 3 4 5 6 |
[quote] .... 引用 改行して引用 .... |
水平線
Markdown も AsciiDoc も同じ。’—‘ または ‘***’
|
1 2 3 |
--- *** |
リンク
AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ
Markdown は[テキスト](URL)の形式。
|
1 2 |
[AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ](https://ryuta46.com/112) |
AsciiDoc は link:URL[テキスト]の形式。Markdown と順序が逆なので注意。
|
1 2 |
link:https://ryuta46.com/112[AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書 |
画像表示
Markdown はの形式。
|
1 2 |
 |
AsciiDoc は image:URL[代替テキスト]の形式。
|
1 2 |
image:logo.png[ロゴ] |
コードブロック
|
1 2 3 4 5 6 7 |
require 'optparse' opt = OptionParser.new opt.on('-a') {|v| p v } opt.on('-b') {|v| p v } opt.parse!(ARGV) p ARGV |
Markdown は ` か ~~~ で囲む形式。
|
1 2 3 4 5 6 7 8 9 |
```ruby require 'optparse' opt = OptionParser.new opt.on('-a') {|v| p v } opt.on('-b') {|v| p v } opt.parse!(ARGV) p ARGV ``` |
AsciiDoc は [source, ruby] のように言語を指定します。ブロック自体は —- で区切る形式。
|
1 2 3 4 5 6 7 8 9 10 |
[source,ruby] ---- require 'optparse' opt = OptionParser.new opt.on('-a') {|v| p v } opt.on('-b') {|v| p v } opt.parse!(ARGV) p ARGV ---- |
テーブル
| ヘッダ1 | ヘッダ2 | ヘッダ3 |
|---|---|---|
| 左寄せ | 中央寄せ | 右寄せ |
| l | c | r |
Markdown は ‘|’ で区切り、’:-‘などでアラインメントを指定する形式
|
1 2 3 4 5 |
|ヘッダ1|ヘッダ2|ヘッダ3| |:--|:--:|--:| |左寄せ|中央寄せ|右寄せ| |l|c|r| |
AsciiDoc も ‘|’ で区切ります。最後の列の後には ‘|’ は不要。
各列の設定は cols で指定し、テーブル全体の設定は options で指定します。ここでは、ヘッダつき、列幅自動調整を指定した場合の例。
|
1 2 3 4 5 6 7 |
[cols="<,^,>",options="header,autowidth"] |============================ |ヘッダ1|ヘッダ2|ヘッダ3 |左寄せ|中央寄せ|右寄せ |l|c|r |============================ |
ちなみにAsciiDoc のテーブルは、’|’ 以外にも CSVの形式で記述できます。また、セルを連結したり、セル内で + で改行したりと、とにかく高機能です。
さいごに
繰り返しになりますが、今回の記事は Markdown でできる表現を AsciiDoc でどう書くか、という視点で書いています。
そのため、AsciiDoc でのみできる表現についてはあまり触れていません。
なんとなく、書き方は「似たようなものだな」というくらいの認識で良いと思います。
ちょっと AsciiDoc の方が形式張っている印象があるかもしれませんが、その分表現できることが AsciiDoc の方が豊かになっています。
特にテーブルは恐ろしく高機能で、テーブル目的で AsciiDoc を使うという選択もアリだと思います。
テーブルの機能も含め、Asciidoc 独自の話はAsciiDocを全力で勧める 4つの理由に記載しました。
よし、AsciiDoc 使ってみるか！でも何からやれば？という方はこちらの記事で導入、使用方法など記載してますので参考にしてください。
AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ
最後まで読んでいただきありがとうございます。 このブログを「いいな」と感じていただけましたら、Twiter にてフォローいただけるとうれしいです。ブログ更新情報などもお届けします。
Follow @ryuta461
この記事をシェアする