AsciiDocは記事、書籍、Webページ、マニュアルなどをプレーンテキストで書くための軽量マークアップ言語です。 本ガイドはAsciidocドキュメントとマークアップ形式テキストのクイックリファレンスです。

本ガイドに記載している例は、HTML形式で生成されたドキュメントの出力結果です。 AsciiDocはその他にもPDF, EPUB, DocBook形式でドキュメントを出力できます。

Asciidoctor限定とレベル付けされた文法を、Pythonで実装された旧AsciiDocで使う場合、 Asciidoctor用に提供されているthis AsciiDoc configuration fileを使う必要があります。

1. 段落

1.1. 基本的な書き方

段落を記載するのに特別なマークアップは不要です。
1行から複数行に渡り連続して記述するだけです。

新しい段落を始める時は、最低1行の空白行を入れてください。

段落を記載するのに特別なマークアップは不要です。 1行から複数行に渡り連続して記述するだけです。

新しい段落を始める時は、最低1行の空白行を入れてください。

1.2. 改行

プラスを行末に指定すると改行とみなされます。 +
ルビーの色は赤です。 +
トパーズの色は青です。

[%hardbreaks]
段落にhardbreaksを指定するとテキスト上での改行が、
そのまま改行として表示されます。
ルビーの色は赤です。
トパーズの色は青です。

プラスを行末に指定すると改行とみなされます。
ルビーの色は赤です。
トパーズの色は青です。

段落にhardbreaksを指定するとテキスト上での改行が、
そのまま改行として表示されます。
ルビーの色は赤です。
トパーズの色は青です。

1.3. リテラル

段落その1

 1つ以上の空白で始まる連続した行はリテラル段落とみなされます。
 リレラル段落はあらかじめフォーマットされたテキストとして扱われます。
 テキストは固定幅のフォントで表示され、
 改行はそのまま改行として表示されます。

段落その2

段落その1

1つ以上の空白で始まる連続した行はリテラル段落とみなされます。
リレラル段落はあらかじめフォーマットされたテキストとして扱われます。
テキストは固定幅のフォントで表示され、
改行はそのまま改行として表示されます。

段落その2

1.4. 脚注

NOTE: 脚注段落は補足情報を示すものです。
段落冒頭のラベルによって脚注の種類を使い分けることができます。

NOTE以外にも下記のような脚注があります。

TIP: チップスを記述します。

IMPORTANT: 重要事項を記述します。

WARNING: 警告を記述します。

CAUTION: 注意を記述します。
脚注段落は補足情報を示すものです。 段落冒頭のラベルによって脚注の種類を使い分けることができます。

NOTE以外にも下記のような脚注があります。

チップスを記述します。
重要事項を記述します。
警告を記述します。
注意を記述します。
脚注ブロックのような書き方も可能です。

1.5. 第一段落

[.lead]
この段落は、第一段落のスタイル(文字が大きいスタイル)が適用されます。

この段落は、第一段落のスタイル(文字が大きいスタイル)が適用されます。

Asciidoctorのデフォルトスタイルシートの場合、序文の最初の段落に第一段落のスタイルが自動で適用されます。

1.6. 詳細な例

段落、リテラル、脚注ブロックのより詳細な例は、Asciidoctor User Manual の下記セクションを参考にしてください。

2. テキストフォーマット

2.1. 太字、イタリック、モノスペース

フォーマット対象文字列の左右にスペースがある場合は、1つの演算子で囲みます。 +
スペースが無い場合(文章の途中、単語の一部)などの場合は、2つの演算子で囲みます。

*太字の語句* と **太**字の文**字**

_イタリックの語句_ と __イタ__リックの文__字__

*_太字のイタリックの語句_* と **__太字のイタ__**リックの文**__字__**

`モノスペースの語句`と``モノ``スペースの文``字``

`*モノスペースの太字の語句*` と ``**モノ**``スペースの太字の語``**句**``

`_モノスペースのイタリックの語句_` と ``__モノ__``スペースのイタリックの文``__字__``

`*_モノスペースの太字のイタリックの語句_*` と ``**__モノ__**``スペースの太字のイタリックの``**__文字__**``

フォーマット対象文字列の左右にスペースがある場合は、1つの演算子で囲みます。
スペースが無い場合(文章の途中、単語の一部)などの場合は、2つの演算子で囲みます。

太字の語句字の文

イタリックの語句イタリックの文

太字のイタリックの語句太字のイタリックの文

`モノスペースの語句`とモノスペースの文

モノスペースの太字の語句モノスペースの太字の語

モノスペースのイタリックの語句モノスペースのイタリックの文

モノスペースの太字のイタリックの語句モノスペースの太字のイタリックの文字

2.2. マーカ、その他

狼男は #シナモン# アレルギーです。

狼男たちは [.small]#小さい活字# を読みましたか?

全ての [.underline]#コア# はどこに流れたのですか?

[.line-through]#10# 20台のVMを用意する必要があります。

[.big]#い# ったん無限ループが起きると

狼男は シナモン アレルギーです。

狼男たちは 小さい活字 を読みましたか?

全ての コア はどこに流れたのですか?

10 20台のVMを用意する必要があります。

ったん無限ループが起きると

2.3. 上付き文字、下付き文字

^上付き文字の^サンプルテキスト

~下付き文字の~サンプルテキスト

上付き文字のサンプルテキスト

下付き文字のサンプルテキスト

2.4. カーブクォート、アポストロフィ

"`ダブルカーブクォート`"

'`シングルカーブクォート`'

Olaf's desk was a mess.

All of the werewolves`' desks were a mess.

Olaf had been with the company since the `'60s.

“ダブルカーブクォート”

‘シングルカーブクォート’

Olaf’s desk was a mess.

All of the werewolves’ desks were a mess.

Olaf had been with the company since the ’60s.

2.5. 詳細な例

テキストフォーマットの詳細な例は、Asciidoctor User Manualの下記セクションを参考にしてください。

3. ドキュメントヘッダー

ヘッダーはオプションです。
ヘッダーは空行は不可です。またコンテンツと最低1行以上間隔を開ける必要があります。

3.1. タイトル

= 本ドキュメントのタイトル

本ドキュメントは...

3.2. タイトル、著者

= 本ドキュメントのタイトル
著者名 <doc.writer@asciidoctor.org>


本ドキュメントは...
著者が複数人の場合はセミコロンで区切って記載してください。

3.3. タイトル、著者、リビジョン

= 本ドキュメントのタイトル
著者名 <doc.writer@asciidoctor.org>
v1.0, 2014-01-01

本ドキュメントは...
リビジョンを定義する場合、著者の定義は必須です。

3.4. タイトル、属性

= 本ドキュメントのタイトル
著者名 <doc.writer@asciidoctor.org>
v1.0, 2014-01-01
// ドキュメントの属性を下記のように定義します。
:toc:
:imagesdir: assets/images
:homepage: http://asciidoctor.org

本ドキュメントは...

4. セクションタイトル

4.1. DocTypeがArticleの場合

= ドキュメントのタイトル(レベル0)

== レベル1のセクションのタイトル

=== レベル2のセクションのタイトル

==== レベル3のセクションのタイトル

===== レベル4のセクションのタイトル

====== レベル5のセクションのタイトル

== 別のレベル1のセクションのタイトル

ドキュメントのタイトル(レベル0)

レベル1のセクションのタイトル

レベル2のセクションのタイトル

レベル3のセクションのタイトル

レベル4のセクションのタイトル
レベル5のセクションのタイトル

別のレベル1のセクションのタイトル

DocTypeがArticleの場合(DocTypeのデフォルト値はArticle)、ドキュメントにレベル0のタイトルは1つしか定義できません。 また必ずドキュメントヘッダーに定義してください。
=の数がHTMLのヘッダータグのレベルと一致しています。例えばレベル1のセクションタイトル<h2>に相当します。

4.2. DocTypeがBookの場合

= ドキュメントのタイトル(レベル0)

== セクション レベル1

=== セクション レベル2

==== セクション レベル3

===== セクション レベル4

====== セクション レベル5

== セクション レベル1

ドキュメントのタイトル(レベル0)

セクション レベル1

セクション レベル2

セクション レベル3

セクション レベル4
セクション レベル5

セクション レベル1

4.3. id

[[primitives-nulls]]
== セッションタイトルの上に[[]]で指定することでidを指定できます。

4.4. セクションアンカーとリンク

sectanchors

このドキュメント属性が設定されている場合、セクションアイコンアンカーが表示されます。

sectlinks

このドキュメント属性が設定されている場合、セクションタイトルに自分自身へのリンクが付きます。 これによりセクションのブックマークが可能になります。

セクションタイトルアンカーは、プロパティをレンダリングするデフォルトのAsciidoctorのスタイルシートに依存します。

5. ファイルのインクルード

5.1. ファイル名指定

= ドキュメントのリファレンス
開発者向け

includeステートメントを指定することで別ファイルをインクルードできます。 +
ファイル名の後の[]は、インクルードファイルのタグや行数を指定して、 +
ファイルの一部だけをインクルードすることができます。

include::basics.adoc[]

include::installation.adoc[]

include::example.adoc[]
Asciidoctorはコンテンツを隔てるために、 隣接したincludeステートメントの間に空行を挿入するようなことはしません。 空行を勝手に挿入すると、セクションタイトルを無効にしてしまうような思わぬ結果を招いてしまうからです。

5.2. URI指定

inclueステートメントにはURIを指定することもできます。

include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[]

URIによるインクルードは、セーフモードが`SECURE`かそれ以上の場合は無効になります。 たとえセーフモードがSECIREよりも低いとしても、 URIによるインクルードを有効にするために、allow-uri-read属性の指定が必要です。

6. 水平罫線と改ページ

6.1. 水平罫線

```

6.2. 改ページ

<<<

7. リスト

7.1. 順序無しリスト

*を行冒頭に指定することで順序無しリストを定義できます。

* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson

*を行冒頭に指定することで順序無しリストを定義できます。

  • Edgar Allen Poe

  • Sheri S. Tepper

  • Bill Bryson

リストの前後には空白行が必須です。
行コメントで二つのリストを分割できます。 コメント中の(^)はオプションで、この行がリストの終わりということを意味するマーカです。

7.2. 順序無しリストのネスト

* レベル1
** レベル2
*** レベル3
**** レベル4
***** レベル5
* レベル1
順序なしリストのマーカはblocks styleで変更できます。

7.3. チェックリスト

- [*] チェック済みの要素
- [x] これもチェック済みの要素
- [ ] 未チェックの要素
-    通常の順序無しリストの要素
  • チェック済みの要素

  • これもチェック済みの要素

  • 未チェックの要素

  • 通常の順序無しリストの要素

チェックリストはfont-based icons and be interactiveを使うこともできます。

7.4. 順序有りリスト

. 手順1
. 手順2
. 手順3
  1. 手順1

  2. 手順2

  3. 手順3

7.5. 順序有りリストのネスト

. 手順1
. 手順2
.. 手順2a
.. 手順2b
. 手順3
  1. 手順1

  2. 手順2

    1. 手順2a

    2. 手順2b

  3. 手順3

7.6. 順序有りリストのネスト(最大までネスト)

. レベル1
.. レベル2
... レベル3
.... レベル4
..... レベル5
. レベル1
  1. レベル1

    1. レベル2

      1. レベル3

        1. レベル4

          1. レベル5

  2. レベル1

Asciidoctorでは、順序有りリスト用にnumeration stylesをサポートしています。 lowergreekdecimal-leading-zeroなどが用意されています。

7.7. ラベル(単一行)

第一項:: 第一項の定義
第二項:: 第二項の定義
第一項

第一項の定義

第二項

第二項の定義

7.8. ラベル(複数行)

第一項::
第一項の定義
第二項::
第二項の定義
第一項

第一項の定義

第二項

第二項の定義

7.9. Q&A

[qanda]
Asciidoctorとは何ですか?::
  AsciiDocをRubyで実装したものです。
生命、宇宙、そして万物についての究極の疑問の答えは何ですか?:: 42です。
  1. Asciidoctorとは何ですか?

    AsciiDocをRubyで実装したものです。

  2. 生命、宇宙、そして万物についての究極の疑問の答えは何ですか?

    42です。

7.10. リストとラベルの組み合わせ

オペレーティング システム::
  Linux:::
    . Fedora
      * デスクトップ
    . Ubuntu
      * デスクトップ
      * サーバ
  BSD:::
    . FreeBSD
    . NetBSD

クラウド プロバイダー::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace
オペレーティング システム
Linux
  1. Fedora

    • デスクトップ

  2. Ubuntu

    • デスクトップ

    • サーバ

BSD
  1. FreeBSD

  2. NetBSD

クラウド プロバイダー
PaaS
  1. OpenShift

  2. CloudBees

IaaS
  1. Amazon EC2

  2. Rackspace

ラベルはネスト可能です。行の冒頭のスペースは重要ではありません。あってもなくてもいいです。

7.11. アウトライン中の複雑なコンテンツ

* リストの要素は必ず段落を1つ以上含みます。
段落のコンテンツはインデントしていても折り返し可能です。
+
リストの途中に段落やブロックを挿入するには、
その上と下の行にリスト継続用マーカを記述します。
+
リスト継続用マーカ:: プラス記号(`{plus}`)を使います。

* リレラル段落はリスト継続用マーカは不要です。

 $ gem install asciidoctor

* AsciiDocのリストは複雑なコンテンツを含むことができます。
+
[cols="2", options="header"]
|===
|アプリケーション
|言語

|Asciidoc
|Python

|Asciidoctor
|Ruby
|===
  • リストの要素は必ず段落を1つ以上含みます。 段落のコンテンツはインデントしていても折り返し可能です。

    リストの途中に段落やブロックを挿入するには、 その上と下の行にリスト継続用マーカを記述します。

    リスト継続用マーカ

    プラス記号(+)を使います。

  • リレラル段落はリスト継続用マーカは不要です。

    $ gem install asciidoctor
  • AsciiDocのリストは複雑なコンテンツを含むことができます。

    アプリケーション 言語

    Asciidoc

    Python

    Asciidoctor

    Ruby

8. リンク

8.1. 通常のリンク

http://asciidoctor.org - 自動でリンクになります。

http://asciidoctor.org[Asciidoctor]

https://github.com/asciidoctor[Asciidoctor @ *GitHub*]

http://asciidoctor.org - 自動でリンクになります。

8.2. スペースと特殊文字を含んだリンク

link:++http://example.org/?q=[a b]++[空白を含むURL]

link:http://example.org/?q=%5Ba%20b%5D[特殊文字を含んだリンク]

8.3. Windows版リンク

link:\\server\share\whitepaper.pdf[Whitepaper]

8.4. 相対パス

link:index.html[ドキュメント]

8.5. メールとIRC

devel@dicsuss.arquillian.org - 自動でリンクになります。

mailto:devel@dicsuss.arquillian.org[Arquillianについて議論する]

mailto:devel-join@discuss.arquillian.org[購読する, 購読します, 参加したいです!] - メールの件名と本文が指定できます。

irc://irc.freenode.org/#asciidoctor

devel@dicsuss.arquillian.org - 自動でリンクになります。

購読する - メールの件名と本文が指定できます。

8.6. 属性付きのリンク(Asciidoctor限定)

http://discuss.asciidoctor.org[Asciidoctorについて議論する, role="external", window="_blank"]

http://discuss.asciidoctor.org[Asciidoctorについて議論する^]

http://example.org["Google, Yahoo, Bing^", role="teal"]
属性付きリンクはAsciidoctor限定の機能です。 機能を有効にするにはドキュメントの属性にlinkattrsを指定してください。 機能有効時は、カンマを含むリンクはクォートで囲む必要があります。

8.7. インラインアンカー

[[ブックマーク-A]]インラインアンカーは任意のコンテンツを参照可能にします。

[#ブックマーク-B]#インラインアンカーはこのように指定することもできます。#

anchor:ブックマーク-C[]相互参照

[[ブックマーク-D,最終パラグラフ]]xreflabelは相互参照リンクのリンクとして使用されます。

インラインアンカーは任意のコンテンツを参照可能にします。

インラインアンカーはこのように指定することもできます。

相互参照

xreflabelは相互参照リンクのリンクとして使用されます。

8.8. 内部相互参照

日本語のセクションタイトルの場合、idはタイトル名の冒頭に_を付けたものになります。
内部相互参照は第1引数にid、第2引数に表示名を指定してください。

<<_段落,段落>>のように記述すると、段落のセクションタイトルへのリンクが表示されます。

セクションタイトルへのリンクは、<<_セクションタイトル,セクション>>のように記述します。

日本語のセクションタイトルの場合、idはタイトル名の冒頭に_を付けたものになります。 内部相互参照は第1引数にid、第2引数に表示名を指定してください。

段落のように記述すると、段落のセクションタイトルへのリンクが表示されます。

セクションタイトルへのリンクは、セクションのように記述します。

8.9. ドキュメント間の相互参照

内部相互参照と同じような記述方法で、第1引数のidの前に`ドキュメント名#`を指定します。

<<document-b.adoc#section-b,Section B>> を参照してください。

9. 画像

ドキュメント属性のimagedir(デフォルトは空文字)起点にした相対パスを指定します。 imagedirを指定することで、共通のパスをハードコードするのを防げます。

imagedirは絶対パス、相対パス、URLを指定できます。 画像の読み込みパスに、絶対パスまたはURLを指定した場合はimagedirのプレフィックスは付きません。

9.1. ブロック要素

image::sunset.jpg[]

image::sunset.jpg[夕日]

.山の夕日
[#image-sunset]
[caption="図 1:", link=http://www.flickr.com/photos/javh/5448336655]
image::sunset.jpg[夕日, 300, 200]

image::http://asciidoctor.org/images/octocat.jpg[GitHub mascot]
sunset
夕日
夕日
図 1:山の夕日
GitHub mascot

9.2. インライン要素

クリック image:icons/play.png[Play, title="Play"] パーティーを開始する。

クリック image:icons/pause.png[title="Pause"] 休憩する。

クリック Play パーティーを開始する。

クリック pause 休憩する。

imageというキーワードの後にある二つのコロンはブロック要素の画像を示し、 一つの時はインライン要素の画像を示します。文章と同じ行に画像を挿入するならインライン要素を使いますが、 それ以外の場合はブロック要素を使用すべきです。

9.3. インライン画像(位置指定あり)

image::sunset.jpg[夕日, 150, 150, role="right"] なんて美しい夕日!

image::sunset.jpg[夕日, 150, 150, role="right"] なんて美しい夕日!

画像の位置とフレームには様々な属性を指定できます。

9.4. 画像データ埋め込み

= ドキュメントタイトル
:data-uri:
data-uriを設定すると、アイコンも含め全ての画像がドキュメントの中にdata-uriとして埋め込まれます。
data-uriを設定する代わりに、コマンドラインで-a data-uriオプションを付けることでも埋め込み可能です。

10. 動画

10.1. ブロック要素

video::video_file.mp4[]


video::video_file.mp4[width=640, start=140, options=autoplay]

10.2. Youtube

video::TabMg56daZ0[youtube]

10.3. Vimeo

video::22439234[vimeo]
追加の属性とオプションを設定することで動画を制御できます。

11. ソース

11.1. インライン要素

`types` や `methods` のような参照コード。

typesmethods のような参照コード。

11.2. リテラル(1行)

 コードスニペットは行冒頭に1つのスペースを挿入してください。
コードスニペットは行冒頭に1つのスペースを挿入してください。

11.3. リテラル(ブロック要素)

....
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
....
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n

11.4. タイトル付きブロック要素(シンタックスハイライトなし)

.Gemfile.lock
----
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (0.1.4)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 0.1.4)
----
1. Gemfile.lock
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (0.1.4)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 0.1.4)

11.5. タイトル付きブロック要素(シンタックスハイライトあり)

[[app-listing]]
[source,ruby]
.app.rb
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----
2. app.rb
require 'sinatra'

get '/hi' do
  "Hello World!"
end

11.6. 吹き出し付きブロック要素

[source,ruby]
----
require 'sinatra' // <1>

get '/hi' do // <2>
  "Hello World!" // <3>
end
----
<1> Library import
<2> URL mapping
<3> HTTP response body
require 'sinatra' (1)

get '/hi' do (2)
  "Hello World!" (3)
end
1 Library import
2 URL mapping
3 HTTP response body

11.7. いろいろな吹き出し付きブロック要素

----
ソースコード //<1>
ソースコード #<2>
ソースコード ;;<3>
----
<1> C言語用の行末吹き出しコメント
<2> Ruby、Python、Perlなどの行末吹き出しコメント
<3> Clojure用の行末吹き出しコメント
ソースコード (1)
ソースコード (2)
ソースコード (3)
1 C言語用の行末吹き出しコメント
2 Ruby、Python、Perlなどの行末吹き出しコメント
3 Clojure用の行末吹き出しコメント

11.8. 吹き出し付きXMLブロック要素

[source,xml]
----
<section>
  <title>Section Title</title> <!--1-->
</section>
----
<1> セクションタイトルをここで定義します。
<section>
  <title>Section Title</title> (1)
</section>
1 セクションタイトルをここで定義します。

11.9. ソースファイル読み込み

[source,java]
----
include::StringUtils.java[]
----

11.10. ソースファイル読み込み(相対パス指定)

[source,java]
----
include::{sourcedir}/StringUtils.java[]
----
package example;

public class StringUtils {
    public boolean contains(String a, String b) {
        if(a == null) {
          return false;
        }

        return a.contains(b);
    }
}

11.11. ソースファイル読み込み(インデント指定)

[source,java,indent=0]
----
include::{sourcedir}/StringUtils.java[lines=5..7]
----

[source,java,indent=1]
----
include::{sourcedir}/StringUtils.java[lines=5..7]
----


[source,java,indent=2]
----
include::{sourcedir}/StringUtils.java[lines=5..7]
----
if(a == null) {
  return false;
}
 if(a == null) {
   return false;
 }
  if(a == null) {
    return false;
  }
  • indentが0の場合、インデントは除去されます。(タブは4つのスペースに置換されます。)

  • indentが1以上の場合、基本のインデントレベルが指定した値になります。(タブは4つのスペースに置換されます。)

11.12. 区切り文字なしのブロック要素

[source,xml]
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">


この行は通常のコンテンツです。
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

この行は通常のコンテンツです。

11.13. シンタックスハイライトを有効にするには

source-highlighter属性をドキュメントヘッダーに付けるか、実行時に引数で渡すことで有効になります。

:source-highlighter: pygments

値はcoderayhighlightjsprettifypygmentsを指定できます。

12. ブロック

12.1. サイドバー

.AsciiDocの歴史
****
AsciiDocは、Stuart Rackhamが2002年11月にリリースした
AsciiDocは、DocBookやLaTeXのような専門的な文章を作成するためのもので、
より簡単な文法で専門的は文章が書けるようにデザインされていた。
****
AsciiDocの歴史

AsciiDocは、Stuart Rackhamが2002年11月にリリースした AsciiDocは、DocBookやLaTeXのような専門的な文章を作成するためのもので、 より簡単な文法で専門的は文章が書けるようにデザインされていた。

どんなブロックでも、ブロックの上にタイトルを付けることができます。 タイトルは.で始まるテキスト行です。 .のあとにスペースを定義することはできません。

12.2. 例

.サンプルドキュメント
====
これはAsciiDocのドキュメントのサンプルです。

[listing]
....
= ドキュメントのタイトル
著者名
:toc:

本ガイドは...
....

ドキュメントヘッダーは、必須ではありません。
====
例 1. サンプルドキュメント

これはAsciiDocのドキュメントのサンプルです。

= ドキュメントのタイトル
著者名
:toc:

本ガイドは...

ドキュメントヘッダーは、必須ではありません。

12.3. 脚注

[NOTE]
====
脚注ブロックは複雑はコンテンツを含むことができます。

.リスト
- 一
- 二
- 三

別のパラグラフ
====

脚注ブロックは複雑はコンテンツを含むことができます。

リスト

別のパラグラフ

脚注と吹き出しのアイコン

AsciidoctorではFont-AwesomeとCSSを使って “描く” ことができます。

これらを使うには、ドキュメント属性のfontに値iconsを設定してください. 設定するとHTML生成時にそれぞれの脚注に対して最適なアイコンが選択されます。

inlinestyledでも アイコンは使用可能です。

12.4. ブロッククォート

[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...
____

[quote, Albert Einstein]
A person who never made a mistake never tried anything new.

____
A person who never made a mistake never tried anything new.
____

[quote, Charles Lutwidge Dodgson, 'Mathematician and author, also known as http://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]']
____
If you don't know where you are going, any road will get you there.
____

Four score and seven years ago our fathers brought forth on this continent a new nation…​

— Abraham Lincoln
Address delivered at the dedication of the Cemetery at Gettysburg
A person who never made a mistake never tried anything new.
— Albert Einstein

A person who never made a mistake never tried anything new.

If you don’t know where you are going, any road will get you there.

— Charles Lutwidge Dodgson
Mathematician and author, also known as Lewis Carroll

12.5. ブロッククォート(簡略記法、Asciidoctor限定)

"I hold it that a little rebellion now and then is a good thing,
and as necessary in the political world as storms in the physical."
-- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.
— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11

12.6. Airクォート(Asciidoctor限定)

[, Richard M. Nixon]
""
When the President does it, that means that it's not illegal.
""

When the President does it, that means that it’s not illegal.

— Richard M. Nixon

12.7. 変換せずに出力

++++
<p>
``+``で囲まれたブロックは、変換処理を行わずにそのままHMTLに出力されます。
</p>

<script src="http://gist.github.com/mojavelinux/5333524.js">
</script>
++++

``+``で囲まれたブロックは、変換処理を行わずにそのままHMTLに出力されます。

12.8. オープン

--
オープンブロックは汎用的に使えます。
--

[source]
--
puts "これはソースブロック!"
--

オープンブロックは汎用的に使えます。

puts "これはソースブロック!"

12.9. カスタム置換属性

:version: 0.1.4

[source,xml,subs="verbatim,attributes"]
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>{version}</version>
</dependency>
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>{version}</version>
</dependency>
上記でsubs属性に指定している値の詳細は特殊文字の置換を参照してください。

13. ID,ロール,オプションの指定

13.1. ブロックへのIDとロールの指定

[[goals]]
[role="incremental"]
* Goal 1
* Goal 2

13.2. ブロックへのIDとロールの指定(簡略記法)

[#goals.incremental]
* Goal 1
* Goal 2
  • 簡略記法で複数のroleを指定するには、.区切りで指定してください。

  • 簡略記法においてidroleの順番は特に関係ありません。

13.3. テキストへのIDとロールの指定

[[free_the_world]][big goal]_free the world_

13.4. テキストへのIDとロールを指定(簡略記法、Asciidoctor限定)

[#free_the_world.big.goal]_free the world_

13.5. クオートで囲まれたテキストへのROLEの指定

[rolename]`monospace text`

13.6. オプションの指定

[options="header,footer,autowidth"]
|===
|Cell A |Cell B
|===

13.7. オプションの指定(簡略記法、Asciidoctor限定)

[%header%footer%autowidth]
|===
|Cell A |Cell B
|===

14. コメント

14.1. 行コメント

// 一行コメントです。

14.2. ブロックコメント

////
複数行コメントです。

これはDelimitedブロックです。
////

15. テーブル

15.1. タイトル、ヘッダ付き2×3

.テーブルタイトル
|===
|カラム名1 |カラム名2 |カラム名3 (1)
(2)
|セル11
|セル12
|セル13

|セル21
|セル22
|セル23
|===
表 1. テーブルタイトル

カラム名1

カラム名2

カラム名3 // <1>

セル11

セル12

セル13

セル21

セル22

セル23

1 cols属性が未指定の場合は、最初の1行目のカラムの数がテーブルの列数となります。
2 最初の行のあとが空行の場合は、最初の行はヘッダー行とみなされます。

15.2. ヘッダ付き2×2

[cols="2*", options="header"] (1)
|===
|カラム名1
|カラム名2

|セル11
|セル12

|セル21
|セル22
|===
カラム名1 カラム名2

セル11

セル12

セル21

セル22

1 cols属性の*は繰り返しを表す演算子である。この場合4つのカラム全てにデフォルトのフォーマットが適用されます。 ヘッダー行が1行で定義されていない場合は、cols属性でカラム数を指定し、options属性を指定する必要があります。

15.3. タイトル、ヘッダ付き2×3

[cols="1,1,2", options="header"](1)
.テーブルタイトル
|===
|名前
|カテゴリ
|説明

|Firefox
|ブラウザ
|オープンソースのブラウザです。
標準仕様に準拠しており、高パフォーマンス、高い可搬性という特徴があります。

|Arquillian
|テスト
|革新的かつ高度に拡張可能なテストプラットフォームです。
開発者が実際の自動テストを簡単に作成できるようにします。
|===
表 2. テーブルタイトル
名前 カテゴリ 説明

Firefox

ブラウザ

オープンソースのブラウザです。 標準仕様に準拠しており、高パフォーマンス、高い可搬性という特徴があります。

Arquillian

テスト

革新的かつ高度に拡張可能なテストプラットフォームです。 開発者が実際の自動テストを簡単に作成できるようにします。

1 colsでこのように指定すると、カラム数は3で、それぞれの列幅が1:1:2になるように表示されます。

15.4. AsciiDocコンテンツ入り

[cols="2,2,5a"]
|===
|Firefox
|ブラウザ
|FirefoxはオープンソースのWEBブラウザです。

下記のような特徴があります。:

* 標準仕様準拠
* 高パフォーマンス
* 高い可搬性

http://getfirefox.com[Firefoxをダウンロードする]!
|===

Firefox

ブラウザ

FirefoxはオープンソースのWEBブラウザです。

下記のような特徴があります。:

  • 標準仕様準拠

  • 高パフォーマンス

  • 高い可搬性

15.5. CSVデータ読み込み

[format="csv", options="header"]
|===
アーティスト,トラック,ジャンル
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===
アーティスト トラック ジャンル

Baauer

Harlem Shake

Hip Hop

The Lumineers

Ho Hey

Folk Rock

15.6. CSVデータ読み込み(簡略記法、Asciidoctor限定)

[format="csv", options="header"]
,===
アーティスト,トラック,ジャンル

Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
,===
アーティスト トラック ジャンル

Baauer

Harlem Shake

Hip Hop

The Lumineers

Ho Hey

Folk Rock

15.7. CSVファイル読み込み

|===
include::customers.csv[]
|===

15.8. DSVデータ読み込み(簡略記法、Asciidoctor限定)

:===
Artist:Track:Genre

Robyn:Indestructable:Dance
:===
Artist Track Genre

Robyn

Indestructable

Dance

15.9. 整形、セル結合

[cols="e,m,^,>s", width="25%"]
|===
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|===

1

2

3

4

5

6

7

8

9

10

16. マクロ

マクロを使用するには、ドキュメントヘッダーにexperimental属性を指定します。

16.1. キーボードショートカット

|===
|ショートカット|目的

|kbd:[F11]
|全画面表示

|kbd:[Ctrl+T]
|新規タブを開く

|kbd:[Ctrl+Shift+N]
|シークレットウインドウを開く

|kbd:[Ctrl + +]
|ズーム
|===
ショートカット 目的

F11

全画面表示

Ctrl+T

新規タブを開く

Ctrl+Shift+N

シークレットウインドウを開く

Ctrl++

ズーム

16.2. メニュー

ファイルを保存するにはmenu:File[Save]を選択します。

拡大率をデフォルトに戻すにはmenu:View[Zoom > Reset]を選択します。

ファイルを保存するにはFile ▸ Saveを選択します。

拡大率をデフォルトに戻すにはView ▸ Zoom ▸ Resetを選択します。

16.3. ボタン

完了したら btn:[OK] ボタンを押してください。

ナビゲーターでファイルを選択し、 btn:[開く] をクリックしてください。

完了したら OK ボタンを押してください。

ナビゲーターでファイルを選択し、 開く をクリックしてください。

17. 属性

17.1. 定義と使用方法

:homepage: http://asciidoctor.org
:docslink: http://asciidoctor.org/docs[Asciidoctor's Docs]
:summary: Asciidoctor is a mature, plain-text document format for \
       writing notes, articles, documentation, books, and more. \
       It's also a text processor & toolchain for translating \
       documents into various output formats (i.e., backends), \
       including HTML, DocBook, PDF and ePub.
:checkedbox: pass:normal[{startsb}&#10004;{endsb}]

Check out {homepage}[Asciidoctor]!

{summary}

Check out {docslink} too!

{checkedbox} That's done!

Check out Asciidoctor!

Asciidoctor is a mature, plain-text document format for writing notes, articles, documentation, books, and more. It’s also a text processor & toolchain for translating documents into various output formats (i.e., backends), including HTML, DocBook, PDF and ePub.

Check out Asciidoctor’s Docs too!

[✔] That’s done!

17.2. 属性の優先順位 (高いものから列挙)

  • APIまたはコマンドラインで指定した属性(終端文字が@でないもの)

  • ドキュメント中に定義した属性

  • APIまたはコマンドラインで指定した属性(終端文字が@のもの)

  • デフォルト属性値

ドキュメント中に定義した属性よりも優先度が低い属性をAPIとコマンドラインで指定するには、属性値の終わりに@を付けます。
表 3. 文字列置換用の属性 [1][2][3]
属性名 置換文字 表示形式
blank
なし
empty
なし
sp
スペース1文字
nbsp
&#160;

 

zwsp[4]
&#8203;

wj[5]
&#8288;

apos
&#39;

'

quot
&#34;

"

lsquo
&#8216;

rsquo
&#8217;

ldquo
&#8220;

rdquo
&#8221;

deg
&#176;

°

plus
&#43;

+

brvbar
&#166;

¦

vbar
|

|

amp
&

&

lt
<

<

gt
>

>

startsb
[

[

endsb
]

]

caret
^

^

asterisk
*

*

tilde
~

~

backslash
\

\

backtick
`

`

two-colons
::

::

two-semicolons
;;

;;

cpp
C++

C++

[1] 一部の置換文字はUnicodeですが、 その他は数値文字表現(例えば &#34; のような文字) です。 数値文字表現は、Unicode文字がAsciiDocの構文解析やブラウザでのレンダリングを妨げる可能性がある場合に使用されます。 コンバーターは、数値文字表現をレンダラが理解できる形式に変換します。

[2] AsciiDocでは定義済み属性を再定義可能ですが、 異なるエンコーディング方式で出力する必要がない限り、参照限定で使用することが推奨されます。 これらの属性は、コンテンツと見た目を分離するために効率的です。

[3] AsciiDocではHTMLで定義されている任意の名前文字参照(通称named entities)使用できます。 (例えば、 &euro; は € に変換されます。) ただし、名前文字参照はPDFなどHTML以外の形式で出力する場合、名前解決用の参照テーブルが定義されていないので問題になります。 そのためXMLに定義されている名前文字参照(lt, gt, amp, quot and apos)以外は使わずに、(&#8364; のような)数値文字参照を使うことをおすすめします。

[4] 幅無しスペース(ZWSP)は、長い単語を分割して表示するために使うUnicodeのコードポイントです。

[5] 単語連結子は改行を跨いで1つの単語を表現するためのUnicodeのコードポイントです。

表 4. 環境属性
属性 説明 値の例

asciidoctor

プロセッサーがAsciidoctorの場合に設定する。

asciidoctor-version

Asciidoctorのバージョン

1.5.4

backend

出力ファイルの形式。

html5

basebackend

backend属性の値から最後の数値を除いた値を設定する。 例えばbackendが`docbook5`なら`docbook`を設定する。

html

docdate

ドキュメントの最終更新日[1,2]

2015-01-04

docdatetime

ドキュメントの最終更新日時[1,2]

2015-01-04 19:26:06 GMT+0000

docdir

ドキュメント格納ディレクトリのフルパス

/home/user/docs

docfile

ドキュメントのフルパス

/home/user/docs/userguide.adoc

docname

拡張子を除いたドキュメント名

userguide

doctime

Last modified time of the source document.[1,2]

19:26:06 GMT+0000

doctype

ドキュメントタイプ (article、book、manpageのどれか)

article

embedded

ドキュメント生成時にコンテンツをドキュメント自体に埋め込む場合に設定する。

filetype

出力ファイルの拡張子

html

htmlsyntax

HTMLに出力する時の構文形式(htmlかxhtml)

html

localdate

ドキュメント生成日[2]

2016-02-17

localdatetime

ドキュメント生成日時[2]

2016-02-17 19:31:05 GMT+0000

localtime

ドキュメント生成時間[2]

19:31:05 GMT+0000

outdir

出力ディレクトリのフルパス

/home/user/docs/dist

outfile

出力ファイルのフルパス。

/home/user/docs/dist/userguide.html

outfilesuffix

出力ファイルの拡張子(最初にピリオド含む)。backendによって値が決まる。(htmlなら.htmldocbookなら .xml など) この属性値を定義している場合、 出力ファイルの拡張子に合わせた値に上書かれることはない。変更に対して安全。

.html

safe-mode-level

数値によってセーフモードを指定する。 (UNSAFE=0, SAFE=10, SERVER=10, SECURE=20).

20

safe-mode-name

文字列によってセーフモードを指定する。

SERVER

safe-mode-unsafe

セーフモードをUNSAFEにする場合に指定する。

safe-mode-safe

セーフモードをSAFEにする場合に指定する。

safe-mode-server

セーフモードをSERVERにする場合に指定する。

safe-mode-secure

セーフモードをSECUREにする場合に指定する。

user-home

カレントユーザのホームディレクトリ セーフモードがSERVER以上の場合は、カレントディレクトリからの相対パスとみなす。

/home/user

17.3. 特殊文字の置換

none

何も置換しない。

normal

吹き出し以外の全てを置換する。

verbatim

特定の文字と吹き出しを置換する。

specialchars, specialcharacters

<>、`&`を置換する。

quotes

クォートを置換する。

attributes

属性参照を置換する。

replacements

テキストと文字参照を置換する。

macros

マクロを置換する。

post_replacements

改行文字 (+)を置換する。

17.4. カウンター属性

[caption=""]
.章{counter2:index:0}
|===
|章 |説明

|第{counter:index}章
|第{index}章の説明

|第{counter:index}章
|第{index}章の説明
|===
説明

第1章

第1章の説明

第2章

第2章の説明

18. テキスト置換

表 5. テキストシンボルの置換
名前 テキスト Unicodeの場合のテキスト 描画 備考

Copyright

(C)
&#169;

©

Registered

(R)
&#174;

®

Trademark

(TM)
&#8482;

Em dash

--
&#8212;

 — 

--に囲まれたスペース。

-の両脇にスペースがある場合、&#8201; として置換されます。

ellipses

...
&#8230;

…​

right single arrow

->
&#8594;

right double arrow

=>
&#8658;

left single arrow

<-
&#8592;

left double arrow

<=
&#8656;

apostrophe

Sam's
Sam&#8217;s

Sam’s

アポストロフィはカーブクォートに置換されます。

任意の名前付き、または16進数のXMLエンティティ参照がサポートされています。

19. テキストのエスケープ

19.1. バックスラッシュ

\*アスタリスク* は太字として描画されません。
単語の左右のアスタリスクは変換されません。

\{author} は著者名と解釈されません。
単語の左右の括弧は変換されません。

バックスラッシュは変換時に自動で除去されます。

*アスタリスク* は太字として描画されません。 単語の左右のアスタリスクは変換されません。

{author} は著者名と解釈されません。 単語の左右の括弧は変換されません。

バックスラッシュは変換時に自動で除去されます。

19.2. インライン要素を変換せずに出力

+++<u>下線付きのテキスト</u>+++ は下線付きテキストとして表示されます。

pass:[<u>下線付きのテキスト</u>] は下線付きテキストとして表示されます。

下線付きのテキスト は下線付きテキストとして表示されます。

下線付きのテキスト は下線付きテキストとして表示されます。

20. 目次

20.1. 目次

= AsciiDoc Writer's Guide
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2013-08-01
:toc:

20.2. 目次(右寄せ)

= AsciiDoc Writer's Guide
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2014-08-01
:toc: right
目次のタイトル、レベル、位置はカスタムできます。

21. 参考文献

21.1. リファレンス

_The Pragmatic Programmer_ <<prag>> should be required reading for
all developers.

[bibliography]
- [[[prag]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer:
  From Journeyman to Master. Addison-Wesley. 1999.
- [[[seam]]] Dan Allen. Seam in Action. Manning Publications.
  2008.

The Pragmatic Programmer [prag] should be required reading for all developers.

  • [prag] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999.

  • [seam] Dan Allen. Seam in Action. Manning Publications. 2008.

22. フットノート

22.1. 再利用可能なフットノート

声明その1。footnote:[この声明のついての明確化]

大胆な声明その1.footnoteref:[disclaimer, Opinions are my own.]

大胆な声明その2.footnoteref:[disclaimer]

声明その1。[1]

大胆な声明その1.[2]

大胆な声明その2.[2]


1. この声明のついての明確化
2. Opinions are my own.

23. マークダウン形式

Asciidoctor限定でマークダウン形式での記述が可能です。

23.1. ヘッダー

# ドキュメントのタイトル(レベル0)

## セクション レベル1

### セクション レベル2

#### セクション レベル3

##### セクション レベル4

###### セクション レベル5

## セクション レベル1

# ドキュメントのタイトル(レベル0)

## セクション レベル1

# セクション レベル2

## セクション レベル3

# セクション レベル4

セクション レベル5

## セクション レベル1

23.2. フェンスコードブロック(シンタックスハイライトあり)

```ruby
require 'sinatra'

get '/hi' do
  "Hello World!"
end
```
require 'sinatra'

get '/hi' do
  "Hello World!"
end

23.3. バッククォート

> I hold it that a little rebellion now and then is a good thing,
> and as necessary in the political world as storms in the physical.
> -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11

I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.

— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11

23.4. ブロッククォート

> > What's new?
>
> I've got Markdown in my AsciiDoc!
>
> > Like what?
>
> * Blockquotes
> * Headings
> * Fenced code blocks
>
> > Is there more?
>
> Yep. AsciiDoc and Markdown share a lot of common syntax already.

What’s new?

I’ve got Markdown in my AsciiDoc!

Like what?

  • Blockquotes

  • Headings

  • Fenced code blocks

Is there more?

Yep. AsciiDoc and Markdown share a lot of common syntax already.

23.5. 水平罫線

---

- - -

***

* * *




24. ユーザマニュアルとヘルプ

Asciidoctorについてより学びたい場合は、Asciidoctorガイドユーザーマニュアルをご覧ください。 Asciidoctorのメーリングリストへの参加も忘れずに!質問、コメントお待ちしています。