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
オフライン

VS Code のプラグイン

AsciiDoc Preview (Atom)
オフライン

Atom のプラグイン

AsciiDoc Tiny Editor
オンライン

DocGist
オンライン
ネットに公開可能

AsciiDocLIVE
オンライン

Coding Ground
オンライン


参考文献