AsciiDoc入門 #Markdown

AsciiDocとは

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

利用例

Pro Git book - Github
オライリーの書籍
- Clojure Cookbook - Github
- Programming Scala
- Mastering Bitcoin - Github
- Open Government - Github
O’Reilly Atlas
Neo4j documentation - Github
Git User's Manual

なぜAsciiDocを使うのか

表現力と可読性

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

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

表現力：HTML > AsciiDoc > Markdown
可読性：AsciiDoc ≒ Markdown > HTML

言語	用途
XML	技術文書(DocBook, DITA)
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^	X²
X~2~	X₂
[red]#赤色#	赤色
[underline]#下線#
[line-through]#取り消し線#	~~取り消し線~~
// コメント

リンク

asciidoc

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

リンク

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

asciidoc

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

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

画像

asciidoc

image::https://via.placeholder.com/350x150[代替テキスト]

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）は、人間がシンプルなテキストエディタを使っての入力が容易になるように設計された、簡潔な文法をもつマークアップ言語である。
____

テーブル

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

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	オフライン	VS Code のプラグイン
AsciiDoc Preview (Atom)	オフライン	Atom のプラグイン
AsciiDoc Tiny Editor	オンライン
DocGist	オンライン	ネットに公開可能
AsciiDocLIVE	オンライン
Coding Ground	オンライン

AsciiDoc入門

AsciiDocとは

利用例

なぜAsciiDocを使うのか

表現力と可読性

Markdownの欠点

AsciiDocの利点

AsciiDocの欠点

記法

セクションタイトル

Document Title (Level 0)

Level 1 Section Title

Level 2 Section Title

Level 3 Section Title

Level 4 Section Title

改行

テキスト修飾

リンク

画像

リスト

コードブロック

引用

テーブル

パススルー

外部ファイルの読み込み

エディター

参考文献