Asciidoctorは 高速な テキストプロセッサで AsciiDoc をHTML 5, DocBook 5や他のフォーマットに変換するツールチェインを配布しています. AsciidoctorはRubyで書かれており, RubyGemとしてパッケージされ, RubyGems.org で配布されています. gemはいくつかのLinuxディストリビューション, Fedora, Debian, Ubuntuにも含まれています. Asciidoctorはオープンソース hosted on GitHub で the MIT licenceのもとに配布されます.
Translations of this document are available in the following languages:
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のプレビューのために使われます.
Asciidoctorは下図の左側のパネルに示されるように, 平文で書かれた内容を読み, 右のパネルに描かれるようにHTML 5に変換します. Asciidoctorは枠にとらわれない快適なエクスペリエンスのためにデフォルトスタイルシートをHTML 5ドキュメントに適用します.
AsciidoctorはAsciiDoc文法で書かれたテキストを読み込み解釈し, それからHTML 5, DocBook 5やman(ual)を出力するために内蔵コンバータセットにパースツリーを渡します. 生成された出力をカスタマイズ, あるいは追加のフォーマットをつくるためにあなた自身のコンバータを使うことや Tilt-supported テンプレートを読み込むオプションがあります.
|
📎
|
AsciidoctorはオリジナルのAsciiDoc Pythonプロセッサ(asciidoc.py)の完全互換です.
Asciidoctorテストスイートは > 1,600 tests をAsciiDoc文法との互換性を保証するために有しています.
|
クラシックなAsciiDoc文法に加えて, Asciidoctorは追加のマークアップとフォントベースのicons(例えば, icon:fire[])などのフォーマッティングオプションとUIエレメント(button:[Save])を 受け付けます.
AsciidoctorはHTML 5出力をスタイルするため, モダンで, Foundation に基づいたレスポンシブテーマをも提供します.
AsciidoctorはLinux, OS X (Mac)とWindowsで動き, 下記の Ruby実装の一つを必要とします.
-
CRuby (aka MRI) 2.3 - 2.6
-
JRuby 9.1 - 9.2
-
TruffleRuby (GraalVM)
-
Opal (JavaScript)
|
🔥
|
もし非英語環境のWindowsを使っているなら, Asciidoctorを起動した時に chcp 65001 に変更することを推奨します. 一度この変更をすると, Unicode関連の頭痛の種は消えるでしょう. もしEclipseのようなIDEを使っているなら, 同様にエンコーディングをUTF-8にするのを忘れないでください. AsciidoctorはUTF-8が使われているところで最高の働きを見せます. |
Asciidoctorは (a) gem install コマンド, (b) Bundler あるいは (c) 有名Linuxディストリビューションのパッケージマネージャ を用いてインストールされます.
|
💡
|
Linuxパッケージマネージャを用いてインストールすることの利点は, もしRubyやRubyGemsライブラリがまだインストールされていなかったら, それらを処理してくれることです.
欠点はgemのリリース直後にはすぐには有効にならないことです.
もし最新バージョンを使いたければ, 必ず gem コマンドを使いましょう.
|
ターミナルを開き, 入力しましょう (先頭の`$`は除く):
$ gem install asciidoctor
もし, 先行リリースバージョン(例えばリリース候補版)をインストールしたければ
$ gem install asciidoctor --pre
|
💡
|
アップグレード
もしAsciidoctorの以前のバージョンがインストール済みであれば, 以下によってアップデートできます: $ gem update asciidoctor もし gem update の代わりに $ gem cleanup asciidoctor |
-
プロジェクトフォルダーのルート(かカレントディレクトリ)にGemfileを作成
-
asciidoctorgemをGemfileに以下のように追加:source 'https://rubygems.org' gem 'asciidoctor' # or specify the version explicitly # gem 'asciidoctor', '2.0.6'
-
Gemfileを保存
-
ターミナルを開き, gemをインストール:
$ bundle
gemをアップグレードするには, Gemfileで新バージョンを指定し, bundle を再び実行してください.
bundle update は他のgemもアップデートするため推奨されて いない ので, 思わぬ結果になるかも知れません.
dnfを使いFedora21かそれ以上にインストールするには, ターミナルを開き, 以下を入力してください:
$ sudo dnf install -y asciidoctor
gemをアップグレードするには:
$ sudo dnf update -y asciidoctor
|
💡
|
お使いのシステムは自動的にrpmパッケージをアップデートするよう設定されているかも知れません.その場合, gemのアップデートのためにあなたがすべきことはありません. |
Debian, UbuntuまたはMintにインストールするには, ターミナルを開き, 以下を入力してください:
$ sudo apt-get install -y asciidoctor
gemをアップグレードするには:
$ sudo apt-get upgrade -y asciidoctor
|
💡
|
お使いのシステムは自動的にdebパッケージをアップデートするよう設定されているかも知れません.その場合, gemのアップデートのためにあなたがすべきことはありません. |
パッケージマネージャ(apt-get)によってインストールされたバージョンのAsciidoctorは最新リリースのAsciidoctorではないかもしれません. ディストリビューションのリリース毎に, どのバージョンがパッケージされているかはパッケージリポジトリを調べてください.
|
🔥
|
パッケージマネージャによって管理されているgemをアップデートするのに |
Asciidoctorのインストールに成功すれば, asciidoctor コマンドラインインターフェース(CLI)がPATH中で有効になります.
確認のために, 以下をターミナルで実行しましょう:
$ asciidoctor --version
AsciidoctorのバージョンとRuby環境についての情報がターミナルに出力されたのを見ることができるはずです.
Asciidoctor 2.0.6 [https://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)との統合を意図しています.
asciidoctor コマンドはAsciidoctorをコマンドライン(つまりターミナル)から起動することを可能にします.
次のコマンドはファイルREADME.adocをHTMLに変換し, 結果を同じディレクトリのREADME.htmlに保存します.
生成されたHTMLファイルの名前はソースファイル依存し, その拡張子を .html に変えます.
$ asciidoctor README.adoc
Asciidoctorプロセッサに様々なフラグやスイッチを与えることで制御できます.それは以下を用いて調べることができます:
$ asciidoctor --help
例えば, ファイルを異なるディレクトリに書き出すには:
$ asciidoctor -D output README.adoc
asciidoctor man page はコマンドライン・インタフェースの完全なリファレンスを提供します.
asciidoctor コマンドの使い方についてもっと学ぶには以下を参照してください.
Asciidoctorをアプリケーションの中で使うには, まずgemをrequireする必要があります:
require 'asciidoctor'それから, AsciiDocソースファイルをHTMLファイルに変換できます:
Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe|
|
AsciidoctorをAPI経由で使っている時, デフォルトのセーフモードは :secure です.
セキュアモードでは, include ディレクティブを含むいくつかのコア機能は無効化されています.
もしこれらの機能を有効化したい場合, 明示的にセーフモードを :server (推奨)か :safe にする必要があります.
|
AsciiDoc文字列を埋め込みHTML(HTMLページヘの挿入)へ変換することもできます:
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safeもし完全なHTMLドキュメントを求めるのであれば, header_footer オプションを以下の通り有効にしてください:
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safeパースされたドキュメントにアクセスしたいのなら, 変換を個々のステップに分割することが出来ます:
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convertAsciidoctorの生成する出力が気に入らないのであれば, あなたはそれを変更できる ことを忘れないでください! Asciidoctorはパースされたドキュメントを生成された出力に変換する処理を扱うカスタムコンバーターをサポートしています.
断片的な出力をカスタマイズする簡単な方法の一つはテンプレートコンバーターを使うことです. テンプレートコンバーターによって, ドキュメント中のあらゆるノードの変換を扱うために Tilt-supportedテンプレートファイルを使うことができます.
そのようにすれば, 出力を100%制御することが できます . APIの使い方や出力のカスタマイズ方法についてのより詳しい情報は user manual を参照してください.
free software の精神においては, everyone がこのプロジェクトを改良するのをたすけることが勧められています. もしエラーや手抜かりをソースコード, ドキュメント, あるいはウェブサイトに見つけたのなら, 恥じることなく修正と共にpull requestの開設やissueの送信をしてください. New contributors are always welcome!
あなた にもできることがあります:
-
先行バージョン(alpha, beta or preview)の使用
-
バグレポート
-
新機能提案
-
ドキュメントの執筆
-
仕様の執筆
-
コーディング — パッチでも, 足りなすぎるなんてことはありません
-
typoの修正
-
コメントの追加
-
一貫性のないホワイトスペースの除去
-
テストの記述!
-
-
リファクタリング
-
issues の修正
-
パッチの批評
Contributing ガイドはどうやってスタイルをつくるか, issueを送るか, 機能リクエスト, コーディング, ドキュメンテーションをAsciidoctor Projectにするかについての情報を提供しています.
Asciidoctorプロジェクトはあなたが簡単に著作を書いて, 配布するのをたすけるため開発されています. しかしあなたのフィードバックなしにはできません! ディスカッションリストで, Twitterで, チャットルームで, 質問し, プロジェクトのあらゆる側面について話し合うようお勧めします.
- Discussion list (Nabble)
-
#asciidoctor hashtag or @asciidoctor mention
- Chat (Gitter)
-
以下のプロジェクトサイトに、Asciidoctorに関するさらに詳しい情報やドキュメントがあります。
GitHub上のAsciidoctorはプロジェクトのソースコード, イシュートラッカー, サブプロジェクトを管理しています.
- Source repository (git)
- Issue tracker
- Asciidoctor organization on GitHub
Copyright © 2012-2019 Dan Allen, Ryan Waldron and the Asciidoctor Project. 本ソフトウェアはMITライセンスのもとで自由に使用できます.
詳細は LICENSE ファイルを参照してください.
Asciidoctor は Dan Allen と Sarah White が先導し, Asciidoctorの素晴らしきコミュニティの数多くのメンバからコントリビューションを受けてきました． このプロジェクトは2012年から Nick Hengeveld の プロトタイプ をベースに Ryan Waldron により創始されました.
AsciiDoc は Stuart Rackham により創始され, AsciiDocコミュニティの数多くのメンバからコントリビューションを受けてきました.
リリースごとの変更一覧は CHANGELOG を参照してください.