よく使う AsciiDoc 記法

# はじめに
AsciiDoc のチートシートです。

Markdown すらまともに書けない自分が、Markdown を使って AsciiDoc を書いているので、頭が混乱してくる。
（加えてめちゃくちゃ時間がかかる。。。）

## よく使う記法
こちらのページを参考に、自分がよく使うものをピックアップしています。
基本的に、ソフトウェアの仕様書や、情報共有のためのメモを最低限、書くことができる。くらいのものを選んでいます。

https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/

## ヘッダ
以下は `Level 3` までしか書いていないが、 `Level 5`(=の数は6つ) まで可能。
```text:asciidoc
= Document Title (Level 0)

== Level 1 Section

=== Level 2 Section

==== Level 3 Section
```
![スクリーンショット 2022-08-21 23.25.13.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/ba7b9c3c-3508-fd7f-2148-74a6ad5a116e.png)

## 改行
改行するためには、` +`(半角スペースと+)が必要。
もしくは、`[%hardbreaks]`を入れると、そのブロック内は強制的に改行される。

```text:asciidoc
Roses are red, +
violets are blue.

[%hardbreaks]
A ruby is red.
Java is black.
```
![スクリーンショット 2022-08-21 23.25.47.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/23595de3-3832-f843-deff-96c693ebef7e.png)

## テーブル
タイトル、ヘッダー付きの3行2列のテーブル。
```text:asciidoc
.Table Title
|===
|Column 1, Header Row |Column 2, Header Row

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===
```
![スクリーンショット 2022-08-21 23.27.21.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/095fe785-7112-8d5a-b42f-7e17b7b1c87a.png)

## イメージ(画像)
`image::URL[代替テキスト]`のフォーマットで画像が挿入できる。
`代替テキスト`とは、何らかの原因で画像が表示されなかったときに表示されるテキストのことらしい。(ググれば出てくる)
代替テキストは省略して、`[]`のみでも問題ない。
また、テーブルのように、`.Image Ttile`で、イメージにタイトルを付けることもできる。
```text:asciidoc
.Image Title
image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]
```
![スクリーンショット 2022-08-21 23.29.29.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/237829c7-0b0e-db9a-0b44-0f3a1a2f6fbb.png)

## リスト
### 番号なしリスト
いわゆる、番号のない箇条書き。`* `(アスタリスクと半角スペース)を付ける。
```text:asciidoc
* Level 1 list item
** Level 2 list item
*** Level 3 list item
* Level 1 list item
```
![スクリーンショット 2022-08-21 23.32.11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/c4cd3abb-572a-5178-3999-9543ffa351e2.png)

### 番号ありリスト
順番つきの箇条書き。`. `(ドットと半角スペース)を付ける。
```text:asciidoc
. Level 1 list item
.. Level 2 list item
... Level 3 list item
. Level 1 list item
```
![スクリーンショット 2022-08-21 23.32.43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/2554cd26-dfd4-546b-3727-32497c77ad7d.png)

## 文字装飾
`*strong*`で、**strong** （太字）
`_cannot_`で、*cannot*（イタリック）
`` `OK` ``で、`OK` （モノスペース　いわゆる、コードの一部を表示するときに使うやつ）
これらを組み合わせて使うことができる。
`*_really_*`は、***really***（太字でイタリック）など。
`//`を入れるとコメントに。

```text:asciidoc
It has *strong* significance to me.

I _cannot_ stress this enough.

Type `OK` to accept.

That *_really_* has to go.

Can't pick one? Let's use them `*_all_*`.

// A single-line comment
```
![スクリーンショット 2022-08-21 23.34.01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/441459ab-0b63-6136-e6e5-9e16c7a121d7.png)

`#cinnamon#`でハイライト。
文字の途中でハイライトを入れる場合は、`##Mark##up`のように、`##`で囲む。
下線を引く場合は、`[.underline]#cores#`
取り消し線を引く場合は、`[.line-through]#ten#`


```text:asciidoc
Werewolves are allergic to #cinnamon#.

##Mark##up refers to text that contains formatting ##mark##s.

Where did all the [.underline]#cores# go?

We need [.line-through]#ten# twenty VMs.
```
![スクリーンショット 2022-08-21 23.35.53.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/b764e561-14ef-542f-3a10-4734be7d38c6.png)

## ソースコード
テーブルタイトルと同様、`.Some Ruby code`のように、`.タイトル`で、ソースコードのタイトルを付けることができる。

```text:asciidoc
.Some Ruby code
[source,ruby]
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----
```
![スクリーンショット 2022-08-21 23.37.03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/a85aeed9-24ca-e83c-248b-ee02e616eb60.png)

## リンク
`https://asciidoctor.org`のようにULRの部分に自動的にリンクが張られる。
また、`[Asciidoctor]`は、`[]`内に書かれたテキストで、ハイパーリンクになる。

```text:asciidoc
https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]
```
![スクリーンショット 2022-08-21 23.38.23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/158e91e9-4015-a699-261c-0d9b996e1925.png)

## 補足説明
`NOTE:`をつけると、気をつけたいポイントなどを目立たせて表示することができる。
そのほか、`IMPORTANT:`、`TIP:`、`CAUTION:`、`WARNING:`がある。

```text:asciidoc
NOTE: An admonition draws the reader's attention to auxiliary information.

Here are the other built-in admonition types:

IMPORTANT: Don't forget the children!

TIP: Look for the warp zone under the bridge.

CAUTION: Slippery when wet.

WARNING: The software you're about to use is untested.
```
![スクリーンショット 2022-08-21 23.40.19.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/a32da36d-a504-ba0e-6c5d-64188c2a6152.png)

## 引用
`[quote, 引用元]`のように、引用元を記載する。`,`を入れると、次の行へ。
引用元のURLへリンクを載せる場合は、`''`のようにシングルクウォートで囲む必要がある。

```text:asciidoc
[quote, Charles Lutwidge Dodgson, 'Mathematician and author, also known as https://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]']
____
If you don't know where you are going, any road will get you there.
____
```
![スクリーンショット 2022-08-21 23.41.52.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/bf8fa24e-8e33-591a-6590-6b5882b92dc1.png)


## 目次の自動生成
目次、TOC(Table of Contents)を自動生成する。
ドキュメントのタイトル以下に、`:toc:`を付けるだけ。
タイトルや、表示するセクションレベルなどは、カスタマイズできる。
例えば、`:toclevels: 3`で、セクションレベル3までになる。（デフォルトはセクションレベル2。つまり`===`まで表示される。)
また、`:toc: left`で、TOCの場所を左側に配置できる。右側に配置したい場合は、leftをrightに置き換えればよい。

```text:asciidoc
= Document Title
Doc Writer <doc.writer@email.org>
:toc:
:toclevels: 3
```
以下は、セクションレベル3までのヘッダに対して、目次を生成した例。
文中には、セクションレベル4まであるが、設定したセクションレベル3までしか目次が生成されていない。
![スクリーンショット 2022-08-21 23.50.50.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2796032/daccbfe7-2e95-1ef7-8471-370797519612.png)