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]
----
５行目から１０行目だけを指定して表示することができます!!
もちろん、ソースコードのハイライトもしてくれます！
以下をインストールしてから、
sudo gem install coderay
Asciidocファイルの冒頭に、
:source-highlighter: coderay
を追加しましょう。きれいにハイライトされるはずです。
自動で目次を作ってくれる！
asciidocファイルの冒頭に以下の記述をすると、自動で目次を作ってくれます。
:toc:
:toclevels: 2
日本語のリファレンスもある！
公式のリファレンスを日本語に訳してくれた素晴らしい方がいらっしゃいました。
PDFへの変換方法
以下のサイトがとても参考になります。
asciidocをPDFに変換してみた（asciidoctor-pdf）
ここでは簡単に、何もテーマを指定せずにPDFに変換したいと思います。
まず、以下のものをインストールします。
sudo gem install --pre asciidoctor-pdf
あとは、以下のコマンドを打つだけです。
asciidoctor-pdf ファイル名.adoc
[追記] 2017/8/7
このままだと、文の折り返しがおかしくなることがあります。そこで、asciidoctor-pdf-cjkを使うと、変な折り返しがなく、きれいになります。
以下のコマンドでインストールし、
sudo gem install asciidoctor-pdf-cjk
以下のコマンドを実行します。
asciidoctor-pdf -r asciidoctor-pdf-cjk ファイル名.asc
[追記] 2018/11/26
asciidoctor-pdf-cjk なんて長すぎて打ってられないよと思う方、 エイリアスを追加してコマンド名を設定すればとても便利です。
.bash_profileか.bashrcに以下を追加すると、adocpdfというコマンドが使えるようになります。
function adocpdf() {
asciidoctor-pdf -r asciidoctor-pdf-cjk $@
}
HTMLへの変換方法
asciidoctor -o 出力したいもの.html 変換するもの.adoc
環境はAtomもしくはIntelliJがおすすめ
Atomでは、AsciiDoc Previewというプラグインを入れるとAtomでAsciidocを編集することができます。
IntelliJでは、Asciidocというプラグインがあるので、それを使いましょう。
なぜこれらのツールでAsciidocを書いた方がいいかというと、プログラムを編集・実行しながらドキュメントをかけるからです！
実用例
以下にAsciidocでかかれた技術書などが一覧になっています。
http://asciidoc.org/#X6
これを見てみると、オライリー本のProgramming Scalaは、Asciidocでかかれていたんですね！
お手軽に始めたい方は
Docker環境が入っているのであれば、asciidocをインストールせずに、コンテナを立ち上げるだけでAsciidoc環境が使えます！！
以下のコマンドを叩けばAsciidoc環境が手に入ります！簡単ですね！
docker run --rm -it -v $(pwd):/documents htakeuchi/docker-asciidoctor-jp
この環境ならasciidoctorやasciidoctor-pdfのようなコマンドが使えますね。
asciidoctor sample.adoc
気になったこと
- 画像の名前は英語名でないと、PDFに出力できなかった。
- Asciidoc内で、セクションの
=（markdownでいう＃）は、タイトルだけにしか使えない。残りの見出しは、==や===などにする必要がある。 - インラインのコードをかく時は、バッククォート２つ必要
参考
あとがき
テキストベースで管理できて、markdownよりも機能が豊富なAsciidoc。
テーマとかいろいろ変えてみると、面白そうです。
追記
2017/8/7
PDFで出力するとき、日本語の一文が長いと折り返しがおかしくなることがあり、そのときは改行を多く用いてその場しのぎをしていました。
しかし、asciidoctor-pdf-cjkを使うことで無事解決しました。（@raccy さん、ありがとうございます）
2019/09/17
Docker環境が入ってればお手軽にAsciidoc環境が手に入ります。お手軽に始めたい方は