Markdown
asciidoc

AsciiDoc入門

AsciiDocとは

AsciiDocはMarkdownなどのような軽量マークアップ言語の一つです。

利用例

なぜAsciiDocを使うのか

表現力と可読性

技術文書を書く場合HTMLは汎用性が高いが可読性が低い、一方Markdownは可読性が高いがテーブル記法がないなど表現力が乏しい。

AsciiDocは可読性が高く表現力もある程度高いので、技術文書等を書くには最適である。

  • 表現力:HTML > AsciiDoc > Markdown
  • 可読性:AsciiDoc ≒ Markdown > HTML
言語 用途
XML 技術文書(DocBook)
HTML Web・電子書籍(EPUB,HTMLBook)
AsciiDoc メモ・技術文書
GitHub Flavored Markdown メモ(プログラマー)
Markdown メモ

Markdownの欠点

  • 記法を拡張する方法が言語仕様に定められていないため、方言が乱立している。その結果、互換性のないものとなっている。
  • HTMLのタグを使うことで拡張できるが、可読性が低くなる。

AsciiDocの利点

  • Markdownと同等の可読性で、表現力が高い。
  • 記法を拡張する方法が言語仕様に定められている。

AsciiDocの欠点

  • Markdownに比べ普及していない。

記法

ここではAsciiDocの記法の一部を紹介する。
より詳しく知るにはAsciiDoc cheatsheet公式サイトを参照。

セクションタイトル

asciidoc
= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

Document Title (Level 0)

Level 1 Section Title

Level 2 Section Title

Level 3 Section Title

Level 4 Section Title

改行

asciidoc
line1 +
line2

line1
line2

テキスト修飾

書式 表示
*bold* bold
_italic_ italic
`monospace` monospace
X^2^ X2
X~2~ X2
[red]#赤色# 赤色
[underline]#下線# 21f89c157c6f08dcc86c881234dbaed6.png
[line-through]#取り消し線# 取り消し線
// コメント

リンク

asciidoc
http://asciidoctor.org/[リンク]

リンク

※ 行頭にリンクを書かない場合は、URLの前に空白文字またはlink:が必要です。

asciidoc
ホニャララ http://asciidoctor.org/[Asciidoctor]
ホニャララlink:http://asciidoctor.org/[Asciidoctor]

ホニャララ Asciidoctor
ホニャララAsciidoctor

画像

asciidoc
image::http://placehold.it/350x150[代替テキスト]

代替テキスト

リスト

asciidoc
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
  • level 1
    • level 2
      • level 3
        • level 4
          • level 5
  • level 1
asciidoc
. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3
  1. Step 1
  2. Step 2
    a. Step 2a
    b. Step 2b
  3. Step 3
asciidoc
CPU:: コンピューターの中心的な処理装置
RAM:: 読み書き可能な主記憶装置
SSD:: フラッシュメモリを使用した補助記憶装置
キーボード:: キーを押すことで信号を送信する入力装置
マウス:: コンピューターのポインティングデバイス
モニター:: 映像を表示する出力装置
CPU
コンピューターの中心的な処理装置
RAM
読み書き可能な主記憶装置
SSD
フラッシュメモリを使用した補助記憶装置
キーボード
キーを押すことで信号を送信する入力装置
マウス
コンピューターのポインティングデバイス
モニター
映像を表示する出力装置

コードブロック

asciidoc
[source, rust]
----
fn main() {
    println!("Hello World!");
}
----
fn main() {
   println!("Hello World!");
}

引用

asciidoc
[quote, 'https://ja.wikipedia.org/wiki/%E8%BB%BD%E9%87%8F%E3%83%9E%E3%83%BC%E3%82%AF%E3%82%A2%E3%83%83%E3%83%97%E8%A8%80%E8%AA%9E[Wikipedia:軽量マークアップ言語]']
____
軽量マークアップ言語(けいりょうマークアップげんご、英語: lightweight markup language)は、人間がシンプルなテキストエディタを使っての入力が容易になるように設計された、簡潔な文法をもつマークアップ言語である。
____

86cf04ffd67757cf173ebdaa891b4f9b.png

テーブル

asciidoc
.テーブルタイトル
[options="header"]
|=======================
|Col 1|Col 2      |Col 3
|1    |Item 1     |a
|2    |Item 2     |b
|3    |Item 3     |c
|=======================

Table 1. テーブルタイトル

Col 1 Col 2 Col 3
1 Item 1 a
2 Item 2 b
3 Item 3 c
asciidoc
[format="csv"]
|======
1,2,3,4
a,b,c,d
A,B,C,D
|======
1 2 3 4
a b c d
A B C D

パススルー

asciidoc
++++
<ruby>
  <rb>亜米利加</rb>
  <rp>(</rp>
  <rt> アメリカ</rt>
  <rp> )</rp>
</ruby>
++++

亜米利加アメリカ

外部ファイルの読み込み

外部ファイルtest.pyの4~5行目を読み込んで表示する

asciidoc
[source, python]
----
include::test.py[lines=4..5]
----
test.py
num1 = 1.1
num2 = 3.9

sum = float(num1) + float(num2)
print('{0} + {1} = {2}'.format(num1, num2, sum))
sum = float(num1) + float(num2)
print('{0} + {1} = {2}'.format(num1, num2, sum))

エディター

名前 種類 備考
Asciidoc FX オフライン HTML,PDF,Mobi,Epub,DocBookの出力が可能
AsciiDoc Preview (Atom) オフライン Atom のプラグイン
AsciiDoc Tiny Editor オンライン
DocGist オンライン ネットに公開可能
AsciiDocLIVE オンライン
Coding Ground オンライン

参考文献