31
32

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

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

Last updated at Posted at 2017-08-07

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]
----

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というコマンドが使えるようになります。

.bash_profile
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環境が使えます!!

asciidoctor環境をdockerで簡単に構築する

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

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

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

asciidoctor sample.adoc

気になったこと

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

参考

AsciiDoc入門

Asciidoctor User Manual

Asciidoc文法クイックリファレンスの日本語訳

asciidoctor-pdfで社内ドキュメントを書こう

asciidoctor-pdf-cjk

asciidoctor環境をdockerで簡単に構築する

あとがき

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

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

追記

2017/8/7

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

しかし、asciidoctor-pdf-cjkを使うことで無事解決しました。(@raccy さん、ありがとうございます)

2019/09/17

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

31
32
2

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
31
32

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?