Asciidoctor高速な テキストプロセッサで AsciiDoc をHTML5, DocBook 5(4.5)や他のフォーマットに変換するツールチェインを配布しています. AsciidoctorはRubyで書かれており, RubyGemとしてパッケージされ, RubyGems.org で配布されています. gemはいくつかのLinuxディストリビューション, Fedora, Debian, Ubuntuにも含まれています. Asciidoctorはオープンソース hosted on Githubthe MIT licenceのもとに配布されます.

Translations of this document are available in the following languages:

Rubyの行く先, Asciidoctorの追うところ

AsciidoctorはJRubyを用いてJVM上でも実行できます. Javaや他のJVM言語からAsciidoctor APIを直接呼び出すには, AsciidoctorJ を使ってください. AsciidoctorJに基づいた, AsciidoctorプロセッサをApache Maven, GradleやJavadocに統合するプラグインがあります.

AsciidoctorはJavaScriptでも実行可能です. Asciidoctor.js, WebブラウザやNode.jsのようなJavaScript環境で動くAsciidoctorの完全機能版, を生成するために, RubyのソースをJavaScriptにトランスパイルするのに Opalを使います. Asciidoctor.jsはChrome, Atom, Brackets や他のウェブベースのツールの拡張機能としてAsciiDocのプレビューのために使われます.

The Big Picture

Asciidoctorは下図の左側のパネルに示されるように, 平文で書かれた内容を読み, 右のパネルに描かれるようにHTML5に変換します. Asciidoctorは枠にとらわれない快適なエクスペリエンスのためにデフォルトスタイルシートをHTML5ドキュメントに適用します.

Preview of AsciiDoc source and corresponding rendered HTML

AsciiDoc Processing

AsciidoctorはAsciiDoc文法で書かれたテキストを読み込み解釈し, それからHTML5, DocBook5(4.5)やman(ual)を出力するために内蔵コンバータセットにパースツリーを渡します. 生成された出力をカスタマイズ, あるいは追加のフォーマットをつくるためにあなた自身のコンバータを使うことや Tilt-supported テンプレートを読み込むオプションがあります.

Note
AsciidoctorはオリジナルのAsciiDoc Pythonプロセッサ(asciidoc.py)の完全互換です. Asciidoctorテストスイートは > 1,600 tests をAsciiDoc文法との互換性を保証するために有しています.

クラシックなAsciiDoc文法に加えて, Asciidoctorは追加のマークアップとフォントベースのicons(例えば, icon:fire[])などのフォーマッティングオプションとUIエレメント(button:[Save])を 受け付けます. AsciidoctorはHTML5出力をスタイルするため, モダンで, Foundation に基づいたレスポンシブテーマをも提供します.

Requirements

AsciidoctorはLinux, OS X (Mac)とWindowsで動き, 下記の Ruby実装の一つを必要とします.

  • MRI (Ruby 1.8.7, 1.9.3, 2.0, 2.1, 2.2 & 2.3)

  • JRuby (1.7 in Ruby 1.8 and 1.9 modes, 9000)

  • Rubinius 2.2.x

  • Opal (JavaScript)

Caution

もし非英語環境のWindowsを使っているなら, Asciidoctorを起動した時に Encoding::UndefinedConversionError に遭遇するでしょう. これを解決するには使っているコンソールの有効なコードページをUTF-8:

chcp 65001

に変更することを推奨します. 一度この変更をすると, Unicode関連の頭痛の種は消えるでしょう. もしEclipseのようなIDEを使っているなら, 同様にエンコーディングをUTF-8にするのを忘れないでください. AsciidoctorはUTF-8が使われているところで最高の働きを見せます.

Installation

Asciidoctorは (a) gem install コマンド, (b) Bundler あるいは (c) 有名Linuxディストリビューションのパッケージマネージャ を用いてインストールされます.

Tip
Linuxパッケージマネージャを用いてインストールすることの利点は, もしRubyやRubyGemsライブラリがまだインストールされていなかったら, それらを処理してくれることです. 欠点はgemのリリース直後にはすぐには有効にならないことです. もし最新バージョンを使いたければ, 必ず gem コマンドを使いましょう.

(a) gem install

ターミナルを開き, 入力しましょう (先頭の`$`は除く):

$ gem install asciidoctor

もし, 先行リリースバージョン(例えばリリース候補版)をインストールしたければ

$ gem install asciidoctor --pre
Tip
アップグレード

もしAsciidoctorの以前のバージョンがインストール済みであれば, 以下によってアップデートできます:

$ gem update asciidoctor

もし gem update の代わりに gem install を使ってgemを新バージョンにした場合, 複数バージョンがインストールされるでしょう. そのときは, 以下のgemコマンドで古いバージョンを削除しましょう:

$ gem cleanup asciidoctor

(b) Bundler

  1. プロジェクトフォルダーのルート(かカレントディレクトリ)にGemfileを作成

  2. asciidoctor gemをGemfileに以下のように追加:

    source 'https://rubygems.org'
    gem 'asciidoctor'
    # or specify the version explicitly
    # gem 'asciidoctor', '1.5.8'
  3. Gemfileを保存

  4. ターミナルを開き, gemをインストール:

    $ bundle

gemをアップグレードするには, Gemfileで新バージョンを指定し, bundle を再び実行してください. bundle update は他のgemもアップデートするため推奨されて いない ので, 思わぬ結果になるかも知れません.

(c) Linux package managers

DNF (Fedora 21 or greater)

dnfを使いFedora21かそれ以上にインストールするには, ターミナルを開き, 以下を入力してください:

$ sudo dnf install -y asciidoctor

gemをアップグレードするには:

$ sudo dnf update -y asciidoctor
Tip
お使いのシステムは自動的にrpmパッケージをアップデートするよう設定されているかも知れません.その場合, gemのアップデートのためにあなたがすべきことはありません.

apt-get (Debian, Ubuntu, Mint)

Debian, UbuntuまたはMintにインストールするには, ターミナルを開き, 以下を入力してください:

$ sudo apt-get install -y asciidoctor

gemをアップグレードするには:

$ sudo apt-get upgrade -y asciidoctor
Tip
お使いのシステムは自動的にdebパッケージをアップデートするよう設定されているかも知れません.その場合, gemのアップデートのためにあなたがすべきことはありません.

パッケージマネージャ(apt-get)によってインストールされたバージョンのAsciidoctorは最新リリースのAsciidoctorではないかもしれません. ディストリビューションのリリース毎に, どのバージョンがパッケージされているかはパッケージリポジトリを調べてください.

Caution

パッケージマネージャによって管理されているgemをアップデートするのに gem udpate コマンドを使うなといわれるでしょう. そのようなことをするのは, パッケージマネージャがファイル(/usr/local下にインストールされた)を追跡できなくなるためにシステムが不安定な状態にするためです. 単純に, システムgemはパッケージマネージャによってのみ管理されるべきです.

もし, パッケージマネージャによってインストールされたのより新しいバージョンのAsciidoctorを使いたければ, RVMrbenvを使ってRubyをホームディレクトリ(すなわち, ユーザースペース)にインストールするべきです. それから, 安心して gem コマンドをAsciidoctorのアップデート, インストールのために使うことができます. RVMやrbenvを使っているなら, gemはシステムからは孤立した場所にインストールされます.

apk (Alpine Linux)

Alpine Linuxにgemをインストールするには, ターミナルを開き, 以下を入力してください:

$ sudo apk add asciidoctor

gemをアップグレードするには:

$ sudo apk add -u asciidoctor
Tip
お使いのシステムは自動的にapkパッケージをアップデートするよう設定されているかも知れません.その場合, gemのアップデートのためにあなたがすべきことはありません.

Usage

Asciidoctorのインストールに成功すれば, asciidoctor コマンドラインインターフェース(CLI)がPATH中で有効になります. 確認のために, 以下をターミナルで実行しましょう:

$ asciidoctor --version

AsciidoctorのバージョンとRuby環境についての情報がターミナルに出力されたのを見ることができるはずです.

Asciidoctor 1.5.8 [http://asciidoctor.org]
Runtime Environment (ruby 2.4.1p111 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

AsciidoctorはAPIを提供します. APIは他のRubyソフトウェア, Rails, SinatraとGitHub, そして他の言語, Java (via AsciidoctorJ )とJavaScript (via Asciidoctor.js)との統合を意図しています.

Command line interface (CLI)

asciidoctor コマンドはAsciidoctorをコマンドライン(つまりターミナル)から起動することを可能にします.

次のコマンドはファイルREADME.adocをHTMLに変換し, 結果を同じディレクトリのREADME.htmlに保存します. 生成されたHTMLファイルの名前はソースファイル依存し, その拡張子を .html に変えます.

$ asciidoctor README.adoc

Asciidoctorプロセッサに様々なフラグやスイッチを与えることで制御できます.それは以下を用いて調べることができます:

$ asciidoctor --help

例えば, ファイルを異なるディレクトリに書き出すには:

$ asciidoctor -D output README.adoc

asciidoctor man page はコマンドライン・インタフェースの完全なリファレンスを提供します.

asciidoctor コマンドの使い方についてもっと学ぶには以下を参照してください.

Ruby API

Asciidoctorをアプリケーションの中で使うには, まずgemをrequireする必要があります:

require 'asciidoctor'

それから, AsciiDocソースファイルをHTMLファイルに変換できます:

Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe
Warning
AsciidoctorをAPI経由で使っている時, デフォルトのセーフモードは :secure です. セキュアモードでは, include ディレクティブを含むいくつかのコア機能は無効化されています. もしこれらの機能を有効化したい場合, 明示的にセーフモードを :server (推奨)か :safe にする必要があります.

AsciiDoc文字列を埋め込みHTML(HTMLページヘの挿入)へ変換することもできます:

content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safe

もし完全なHTMLドキュメントを求めるのであれば, header_footer オプションを以下の通り有効にしてください:

content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe

パースされたドキュメントにアクセスしたいのなら, 変換を個々のステップに分割することが出来ます:

content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert

Asciidoctorの生成する出力が気に入らないのであれば, あなたはそれを変更できる ことを忘れないでください! Asciidoctorはパースされたドキュメントを生成された出力に変換する処理を扱うカスタムコンバーターをサポートしています.

断片的な出力をカスタマイズする簡単な方法の一つはテンプレートコンバーターを使うことです. テンプレートコンバーターによって, ドキュメント中のあらゆるノードの変換を扱うために Tilt-supportedテンプレートファイルを使うことができます.

そのようにすれば, 出力を100%制御することが できます . APIの使い方や出力のカスタマイズ方法についてのより詳しい情報は user manual を参照してください.

Contributing

free software の精神においては, everyone がこのプロジェクトを改良するのをたすけることが勧められています. もしエラーや手抜かりをソースコード, ドキュメント, あるいはウェブサイトに見つけたのなら, 恥じることなく修正と共にpull requestの開設やissueの送信をしてください. New contributors are always welcome!

あなた にもできることがあります:

  • 先行バージョン(alpha, beta or preview)の使用

  • バグレポート

  • 新機能提案

  • ドキュメントの執筆

  • 仕様の執筆

  • コーディング — パッチでも, 足りなすぎるなんてことはありません

    • typoの修正

    • コメントの追加

    • 一貫性のないホワイトスペースの除去

    • テストの記述!

  • リファクタリング

  • issues の修正

  • パッチの批評

Contributing ガイドはどうやってスタイルをつくるか, issueを送るか, 機能リクエスト, コーディング, ドキュメンテーションをAsciidoctor Projectにするかについての情報を提供しています.

Getting Help

Asciidoctorプロジェクトはあなたが簡単に著作を書いて, 配布するのをたすけるため開発されています. しかしあなたのフィードバックなしにはできません! ディスカッションリストで, Twitterで, チャットルームで, 質問し, プロジェクトのあらゆる側面について話し合うようお勧めします.

Discussion list (Nabble)

http://discuss.asciidoctor.org

Twitter

#asciidoctor hashtag or @asciidoctor mention

Chat (Gitter)

Gitter

GitHub上のAsciidoctorはプロジェクトのソースコード, イシュートラッカー, サブプロジェクトを管理しています.

Copyright © 2012-2018 Dan Allen, Ryan Waldron and the Asciidoctor Project. 本ソフトウェアはMITライセンスのもとで自由に使用できます.

詳細は LICENSE ファイルを参照してください.

Authors

AsciidoctorDan AllenSarah White が先導し, Asciidoctorの素晴らしきコミュニティの数多くのメンバからコントリビューションを受けてきました. このプロジェクトは2012年から Nick Hengeveldプロトタイプ をベースに Ryan Waldron により創始されました.

AsciiDoc は Stuart Rackham により創始され, AsciiDocコミュニティの数多くのメンバからコントリビューションを受けてきました.

Changelog

リリースごとの変更一覧は CHANGELOG を参照してください.