AsciiDoc vs Markdown 比較チートシート

AsciiDoc は Markdown より表現力が高く、Markdown と同じくらい可読性の高い軽量マークアップ言語の一つです。 オライリーの書籍などでも実際に利用されている実績のある言語です。 ただ、あまり普及率が高く無いので、この記事ではその導入ハードルを下げるため、Markdown と AsciiDoc の記述方法の違いを記載します。 AsciiDoc 独自の表現についてはAsciiDocを全力で勧める 4つの理由を書きましたので参照ください。 本記事では、Markdown と AsciiDoc 共通の表現について記載し、AsciiDoc も Markdown と同じくらいかそれ以上に書きやすい言語なんだということを感じ取ってもらえれば。 なお、この記事中の Markdown は GFM(GitHub Flavored Markdown) の事を指しています。

見出し

Markdown は '#' の数でレベルを表現。 AsciiDoc は '=' の数でレベルを表現

改行

途中で
改行 Markdown は行末にスペース二つで改行 AsciiDoc は 行末に '+' を書くと改行

文字装飾

強調

強調(em)イタリック 強調(strong)太字 Markdown は '*' の数で装飾パターンの切り替え('_'でも可) 。 AsciiDoc は '*' と '_' で装飾パターンの切り替え

取り消し線

~~取り消し線~~ Markdown は ~ で囲む。 AsciiDoc は[line-through]* で囲む。 ちなみに line-through を overlineや underline にすることで上線、下線も表現できます。

リスト

箇条書きリスト

  • 項目1
  • 項目2
    • 項目2-1
Markdown は '*'('-'、'+' でも可)。レベルはインデントで表現。 AsciiDoc も '*'で、レベルは '*' の数で表現。最上位のレベルのみ '-' でも可。

番号つきリスト

  1. 項目1
  2. 項目2
    1. 項目2-1
Markdown は '1.'。記載した数字から順に自動で番号が振られる。レベルは箇条書きと同じくインデントで表現。 AsciiDoc は '.'。レベルは箇条書きと同様 '.' の数で表現 ただし、AsciiDoc の場合 2レベル目は a. 項目2-1 のように別の序列が割り当てられます。2レベル移行も数字にしたければ下記のように[arabic]をはさみます。

引用

引用 改行して引用
Markdown は '>'。毎行 '>' を先頭に書く AsciiDoc は [quote] というブロック。レンダラーによって見た目が少し変わるかもしれませんが、意味的には引用時はこれを使います。

水平線



Markdown も AsciiDoc も同じ。'---' または '***'

リンク

AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ Markdown は[テキスト](URL)の形式。 AsciiDoc は link:URL[テキスト]の形式。Markdown と順序が逆なので注意。

画像表示

Markdown は![代替テキスト](URL)の形式。 AsciiDoc は image:URL[代替テキスト]の形式。

コードブロック

Markdown は ` か ~~~ で囲む形式。 AsciiDoc は [source, ruby] のように言語を指定します。ブロック自体は ---- で区切る形式。

テーブル

ヘッダ1 ヘッダ2 ヘッダ3
左寄せ 中央寄せ 右寄せ
l c r
Markdown は '|' で区切り、':-'などでアラインメントを指定する形式 AsciiDoc も '|' で区切ります。最後の列の後には '|' は不要。
各列の設定は cols で指定し、テーブル全体の設定は options で指定します。ここでは、ヘッダつき、列幅自動調整を指定した場合の例。 ちなみにAsciiDoc のテーブルは、'|' 以外にも CSVの形式で記述できます。また、セルを連結したり、セル内で + で改行したりと、とにかく高機能です。

さいごに

繰り返しになりますが、今回の記事は Markdown でできる表現を AsciiDoc でどう書くか、という視点で書いています。 そのため、AsciiDoc でのみできる表現についてはあまり触れていません。 なんとなく、書き方は「似たようなものだな」というくらいの認識で良いと思います。 ちょっと AsciiDoc の方が形式張っている印象があるかもしれませんが、その分表現できることが AsciiDoc の方が豊かになっています。 特にテーブルは恐ろしく高機能で、テーブル目的で AsciiDoc を使うという選択もアリだと思います。 テーブルの機能も含め、Asciidoc 独自の話はAsciiDocを全力で勧める 4つの理由に記載しました。 よし、AsciiDoc 使ってみるか!でも何からやれば?という方はこちらの記事で導入、使用方法など記載してますので参考にしてください。 AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ
最後まで読んでいただきありがとうございます。 このブログを「いいな」と感じていただけましたら、Twiter にてフォローいただけるとうれしいです。ブログ更新情報などもお届けします。



りゅーた
フリーランスのエンジニアしてます。Android、iOS アプリの開発、対向サーバの開発、C/C++のライブラリ開発が現在のメイン。趣味はテニス・ゲーム・自転車。2児の父

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

CAPTCHA