なんと、Asciidocはソースコードをインポートできるよ！

markdownよりもカスタマイズしほうだいのAsciidocを簡単に紹介するよ！

# 対象の方
markdownに限界を感じているあなたへ。

かと言ってWordではないツールをお探しのあなたへ。

**Asciidoc**があります！！

# Asciidocってなあに？
Asciidocは、Webページ、本、記事などを書くための軽量マークアップ言語です。拡張子は`.asciidoc`もしくは`.adoc`

とりあえず、この記事をAsciidocでかくとこんな感じです。
https://v97ug.github.io/introduce-asciidoc/

Asciidocには、markdownにはない便利な機能がたくさんあります。

その便利な機能を紹介しますね。

# ソースコードをインポートできる！

なんと、Asciidocは**ソースコードをインポート**できます！ざっとこんな感じで。

```
[source,java]
----
include::Something.java[]
----
```

`include::`のあとに、ソースコードのパスを記述できます。

そして、最後の`[]`ですが、ここに以下のように記述すると、、、

```
[source,java]
----
include::Something.java[lines=5..10]
----
```

５行目から１０行目だけを指定して表示することができます!!

# もちろん、ソースコードのハイライトもしてくれます！

以下をインストールしてから、

```bash
sudo gem install coderay
```

Asciidocファイルの冒頭に、

```
:source-highlighter: coderay
```

を追加しましょう。きれいにハイライトされるはずです。

# 自動で目次を作ってくれる！

asciidocファイルの冒頭に以下の記述をすると、自動で目次を作ってくれます。

```
:toc:
:toclevels: 2
```

# 日本語のリファレンスもある！

公式のリファレンスを日本語に訳してくれた素晴らしい方がいらっしゃいました。

https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/

# PDFへの変換方法
以下のサイトがとても参考になります。
[asciidocをPDFに変換してみた（asciidoctor-pdf）](https://aimless.jp/blog/archives/2641/)

ここでは簡単に、何もテーマを指定せずにPDFに変換したいと思います。

まず、以下のものをインストールします。

```
sudo gem install --pre asciidoctor-pdf
```

あとは、以下のコマンドを打つだけです。

```
asciidoctor-pdf ファイル名.adoc
```

**[追記] 2017/8/7**
このままだと、文の折り返しがおかしくなることがあります。そこで、[asciidoctor-pdf-cjk](https://github.com/chloerei/asciidoctor-pdf-cjk)を使うと、変な折り返しがなく、きれいになります。

以下のコマンドでインストールし、

```bash
sudo gem install asciidoctor-pdf-cjk
```

以下のコマンドを実行します。

```bash
asciidoctor-pdf -r asciidoctor-pdf-cjk ファイル名.asc
```

**[追記] 2018/11/26**

`asciidoctor-pdf-cjk` なんて長すぎて打ってられないよと思う方、 エイリアスを追加してコマンド名を設定すればとても便利です。
`.bash_profile`か`.bashrc`に以下を追加すると、`adocpdf`というコマンドが使えるようになります。

```bash:.bash_profile
function adocpdf() {
        asciidoctor-pdf -r asciidoctor-pdf-cjk $@
}
```

# HTMLへの変換方法

```
asciidoctor -o 出力したいもの.html 変換するもの.adoc
```

# 環境はAtomもしくはIntelliJがおすすめ

Atomでは、[AsciiDoc Preview](https://atom.io/packages/asciidoc-preview)というプラグインを入れるとAtomでAsciidocを編集することができます。

IntelliJでは、[Asciidoc](https://plugins.jetbrains.com/plugin/7391-asciidoc)というプラグインがあるので、それを使いましょう。

なぜこれらのツールでAsciidocを書いた方がいいかというと、**プログラムを編集・実行しながらドキュメントをかける**からです！

# 実用例
以下にAsciidocでかかれた技術書などが一覧になっています。
http://asciidoc.org/#X6

これを見てみると、オライリー本の[Programming Scala](http://shop.oreilly.com/product/9780596155964.do)は、Asciidocでかかれていたんですね！

# お手軽に始めたい方は

Docker環境が入っているのであれば、asciidocをインストールせずに、コンテナを立ち上げるだけでAsciidoc環境が使えます！！

[asciidoctor環境をdockerで簡単に構築する](https://namaraii.com/post/asciidoctor環境をdockerで簡単に構築する/)

以下のコマンドを叩けばAsciidoc環境が手に入ります！簡単ですね！

```bash
docker run --rm -it -v $(pwd):/documents htakeuchi/docker-asciidoctor-jp
```

この環境なら`asciidoctor`や`asciidoctor-pdf `のようなコマンドが使えますね。

```bash
asciidoctor sample.adoc
```

# 気になったこと
- 画像の名前は英語名でないと、PDFに出力できなかった。
- Asciidoc内で、セクションの`=`（markdownでいう`＃`）は、タイトルだけにしか使えない。残りの見出しは、`==`や`===`などにする必要がある。
- インラインのコードをかく時は、バッククォート２つ必要

# 参考

[AsciiDoc入門](http://qiita.com/xmeta/items/de667a8b8a0f982e123a)

[Asciidoctor User Manual](http://asciidoctor.org/docs/user-manual/)

[Asciidoc文法クイックリファレンスの日本語訳](
https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/)

[asciidoctor-pdfで社内ドキュメントを書こう](http://qiita.com/gho4d76g/items/302e1ff91754b9b50f34)

[asciidoctor-pdf-cjk](https://github.com/chloerei/asciidoctor-pdf-cjk)

[asciidoctor環境をdockerで簡単に構築する](https://namaraii.com/post/asciidoctor環境をdockerで簡単に構築する/)

# あとがき

テキストベースで管理できて、markdownよりも機能が豊富なAsciidoc。

テーマとかいろいろ変えてみると、面白そうです。

# 追記

## 2017/8/7
PDFで出力するとき、日本語の一文が長いと折り返しがおかしくなることがあり、そのときは改行を多く用いてその場しのぎをしていました。

しかし、[asciidoctor-pdf-cjk](https://github.com/chloerei/asciidoctor-pdf-cjk)を使うことで無事解決しました。（@raccy さん、ありがとうございます）

## 2019/09/17

Docker環境が入ってればお手軽にAsciidoc環境が手に入ります。[お手軽に始めたい方は](#お手軽に始めたい方は)