Asciidoctorは, AsciiDoc で書かれたコンテンツをHTML5, DocBook, PDFなどのフォーマットに変換する, 高速で オープンソース のテキストプロセッサおよびパブリッシングツールチェインです. AsciidoctorはRubyで書かれており, すべての主要オペレーティングシステムで動作します. Asciidoctorプロジェクトは GitHubにホスティング されています.
インストールをシンプルにするため, AsciidoctorはRubyGem（gem）パッケージとして, RubyGems.org で配布されています. さらに, Asciidoctorは主要なLinuxディストリビューション用およびmacOS用パッケージとしても配布されています. AsciidoctorはRubyで動作するだけでなく, AsciidoctorJとしてJVM上でも動作します. また, Asciidoctor.jsとしてどのようなJavaScript環境（ブラウザを含む）でも実行できます.
スポンサー のみなさまが, このプロジェクトをサポートし, より良いテクニカルドキュメンテーションの実現にコミットメントをしてくださっていることに感謝します. スポンサーのみなさま, ありがとうございます！ みなさまの多くのサポートなくしてAsciidoctorは実現不可能です.
OpenCollective を通じてスポンサーになることにより, このプロジェクトを支援することができます.
Asciidoctorは, 下図左側のようなプレーンテキストを読み込んで, 右側のようなHTML5に変換します. 特別な設定をしなくてもきれいな表示が得られるよう, HTML5の出力にはデフォルトのスタイルシートが適用されます.
Asciidoctorは, AsciiDoc文法で書かれたテキストを読み込んでパースします. 次に内蔵コンバータにパースツリーを渡します. これによりHTML5, DocBook 5やman(マニュアルmanページ)が出力されます. 出力をカスタマイズしたりフォーマットを追加したりしたいときは, ユーザ独自のコンバータや Tilt 対応テンプレートを使用することができます.
AsciidoctorはオリジナルのAsciiDoc Pythonプロセッサ(asciidoc.py)に完全互換です.
Asciidoctorのテストスイートには, AsciiDoc文法との互換性を保証するために 2350個を超えるテスト が入っています.
Asciidoctorでは, AsciiDocの従来の文法のほかに, Asciidoctorで追加されたマークアップとフォーマッティングオプションが使用できます. フォントベースのアイコン (例えば, icon:fire[]) やUIエレメント(button:[Save])がそれにあたります.
またAsciidoctorは, HTML5出力時のスタイルとして Foundation に基づいたモダンでレスポンシブなテーマも提供します.
AsciidoctorはJRubyを用いてJVM上でも実行できます. Javaや他のJVM言語からAsciidoctor APIを直接呼び出すには, AsciidoctorJ を使ってください. AsciidoctorJを使ったAsciiDocの処理をビルドに直接組み込むビルドツール用プラグインとして, Apache Maven用, Gradle用, および Javadoc用 が存在します.
AsciidoctorはJavaScriptでも実行可能です. Rubyで書かれたソースを Opal を使ってJavaScriptにトランスパイルすることで Asciidoctor.js が作成されています. Asciidoctor.jsはどんなJavaScript環境（WebブラウザやNode.jsを含む）でも動作する, JavaScript版の完全なAsciidoctorです. Chrome, Atom, Bracketsやその他のウェブベースのツールで, AsciiDocをプレビューするための拡張機能にAsciidoctor.jsが使われています.
AsciidoctorはLinux, macOS, およびWindowsで動作し, 下記の Ruby実装の一つを必要とします.
-
CRuby (aka MRI) 2.5 - 3.1
-
JRuby 9.1 - 9.3
-
TruffleRuby (GraalVM)
-
Opal (JavaScript)
|
🔥
|
もし非英語環境のWindowsを使っているなら, Asciidoctorを起動した時に chcp 65001 一度この変更をすると, Unicode関連の頭痛の種は消えるでしょう. もしEclipseのようなIDEを使っているなら, 同様にエンコーディングをUTF-8にするのを忘れないでください. AsciidoctorはUTF-8の環境において最も良好に動作します. |
Asciidoctorは, (a) 主なLinuxディストリビューションのパッケージマネージャ, (b) macOSのHomebrew, (c) gem install コマンド（Windowsユーザに推奨）, (d) Asciidoctor Dockerイメージ, あるいは(e) Bundlerを用いてインストールできます.
Linuxパッケージマネージャを用いてインストールする利点は, もしRubyやRubyGemsライブラリがまだインストールされていなかったら, それらをインストールしてくれることです.
パッケージマネージャによってインストールされるAsciidoctorは最新バージョンではないかもしれません. ディストリビューションの各リリースにおいてどのバージョンのAsciidoctorがパッケージされているかを確認するには, パッケージリポジトリを参照してください.
パッケージマネージャによってインストールされるバージョンよりも新しいAsciidoctorを使用したい場合は, gemのインストール方法 を参照してください.
Archベースのディストリビューションにgemをインストールするには, ターミナルを開き, 以下を入力してください:
$ sudo pacman -S asciidoctor
Debian, またはUbuntuなどDebianベースのディストリビューションでは, APTを使ってAsciidoctorをインストールしてください. Asciidoctorパッケージをインストールするには, ターミナルを開き, 以下を入力してください:
$ sudo apt-get install -y asciidoctor
macOSでは, パッケージマネージャHomebrewを使用してAsciidoctorをインストールすることができます.
Homebrewをお持ちでない場合は, まず brew.sh の説明に従ってHomebrewをインストールしてください.
Homebrewをインストールできたら, asciidoctor gemをインストールすることができます.
ターミナルを開き, 以下を入力してください:
$ brew install asciidoctor
Homebrewにより, システムレベルのgemとは別の独立したprefixのパスに asciidoctor gemがインストールされます.
WindowsでAsciidoctorを使う場合は, 簡単な方法が2つあります.
すでにお使いのマシンで chocolatey を使用しているなら, 以下の方法を使用することができます:
choco install ruby
そのあとは gemのインストール方法 に従ってください.
Rubyinstaller を使用したい場合は, お使いのWindowsのバージョンに適したRubyinstallerをダウンロードしてRubyをインストールしたあと, gemのインストール方法 に従ってください.
Asciidoctorを gem install を使ってインストールするのであれば, その前に RVM を使ってhomeディレクトリ（つまりユーザ領域）にRubyをインストールしておくべきです.
そうすれば, gem コマンドを使用して安全にAsciidoctor gemのインストールやアップデートができます.
RVMを使用すると, システムから隔離された場所にgemがインストールされます.
ターミナルを開き, 以下のように入力してください:
$ gem install asciidoctor
もし, 先行リリースバージョン(例えばリリース候補版)をインストールしたければ以下のようにします.
$ gem install asciidoctor --pre
Installing Asciidoctor using Dockerを参照してください.
-
プロジェクトのルートフォルダ(またはカレントディレクトリ)にGemfileを作成
-
asciidoctorgemをGemfileに以下のように追加:source 'https://rubygems.org' gem 'asciidoctor' # または明示的にバージョンを指定 # gem 'asciidoctor', '2.0.22'
-
Gemfileを保存
-
ターミナルを開き, gemをインストール:
$ bundle
gemをアップグレードするには, Gemfileで新バージョンを指定し, bundle を再び実行してください.
bundle update を（gemを指定せずに）行うことは推奨 されません . 他のgemもアップデートされて思わぬ結果になるかもしれないためです.
オペレーティングシステムのパッケージマネージャでAsciidoctorをインストールしたのであれば, おそらくパッケージは自動的にアップデートされるように設定されています. その場合は, gemを手動でアップデートする必要はありません.
Asciidoctorのインストールが成功すると, asciidoctor コマンドがPATHに存在するようになり, Asciidoctorのコマンドラインインターフェース(CLI)が使用できるようになります.
確認のために, ターミナルで以下を実行しましょう:
$ asciidoctor --version
AsciidoctorのバージョンとRuby環境についての情報がターミナルに出力されるはずです.
Asciidoctor 2.0.22 [https://asciidoctor.org] Runtime Environment (ruby 3.0.1p64 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
AsciidoctorはAPIも提供します. APIは他のRubyソフトウェア, たとえばRails, Sinatra, GitHub, そして他の言語, たとえばJava (AsciidoctorJ 経由)やJavaScript (Asciidoctor.js 経由)と組み合わせて使用するためのものです.
asciidoctor コマンドによりコマンドライン(つまりターミナル)からAsciidoctorを起動することができます.
次のコマンドにより, README.adocというファイルがHTMLに変換され, 結果が同じディレクトリのREADME.htmlとして保存されます.
生成されるHTMLファイルの名前は, ソースファイルのファイル名の拡張子を .html に替えたものとなります.
$ asciidoctor README.adoc
さまざまなフラグやスイッチを与えることでAsciidoctorプロセッサをコントロールすることができます. フラグやスイッチの説明は以下のコマンドで表示されます:
$ asciidoctor --help
例えば, ファイルを異なるディレクトリに書き出すには以下を使用します:
$ asciidoctor -D output README.adoc
コマンドラインインタフェースの完全なリファレンスは asciidoctor の manページ にあります.
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の生成する出力が気に入らない場合は, あなたはそれを変更できる ことを忘れないでください! パースされたドキュメントを出力形式に変換するコンバータは, カスタマイズが可能です.
出力を部分的にカスタマイズする簡単な方法としてはテンプレートコンバータがあります. テンプレートコンバータでは, ドキュメントの各ノードの変換に Tilt対応テンプレートファイルを使うことができます.
さまざまな方法を使って出力は100%制御することが できます . APIの使い方や出力のカスタマイズ方法についてのより詳しい情報は ユーザマニュアル を参照してください.
新しいコントリビューションを常に歓迎します! もしソースコード, ドキュメント, あるいはウェブサイトに間違いや不備を見つけたら遠慮なく, イシューを作成するか, 修正をおこなってpull requestを作成してください.
あなた にもできることがあります:
-
先行バージョン(alpha, beta, またはpreview版)の使用
-
バグレポート
-
新機能提案
-
ドキュメントの執筆または編集
-
テストをつけてコードを書くこと — どのようなパッチであれ小さすぎるなどということはありません
-
typoの修正
-
コメントの追加
-
一貫性のないホワイトスペースの除去
-
テストの記述!
-
-
リファクタリング
-
イシュー の解決
-
パッチのレビュー
Asciidoctorプロジェクトにイシュー, 機能リクエスト, コード, ドキュメントを送る際の, 作成方法, スタイル, および送り方は, Contributing ガイドに記載されています.
Asciidoctorは, コンテンツの執筆と公開を簡単にするために開発されています. しかしあなたからのフィードバックがなくてはAsciidoctorの開発は進みません! ディスカッションリスト, Twitter, チャットルームを使って, 質問をしたりプロジェクトのさまざまな側面について話し合ったりすることをお勧めします.
- チャット(Zulip)
- ディスカッションリスト(Nabble)
-
ハッシュタグ #asciidoctor またはメンション @asciidoctor
以下のプロジェクトサイトに, Asciidoctorに関するさらに詳しい情報やドキュメントがあります.
GitHub上のAsciidoctorのorganizationではプロジェクトのソースコード, イシュートラッカー, サブプロジェクトが管理されています.
- ソースリポジトリ(git)
- イシュートラッカー
- GitHub上のAsciidoctorのorganization
Copyright © 2012-present Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor. 本ソフトウェアはMITライセンスのもとで使用できます.
ライセンスの詳細については LICENSE ファイルを参照してください.
Asciidoctor は Dan Allen と Sarah White がリードし, Asciidoctorの素晴らしきコミュニティの 数多くのメンバ からコントリビューションを受けてきました． このプロジェクトは Nick Hengeveld のプロトタイプをベースに Ryan Waldron により2012年から創始されました.
AsciiDoc は Stuart Rackham により創始され, AsciiDocコミュニティの数多くのメンバからコントリビューションを受けてきました.
過去のリリースの完全な変更点リストについては CHANGELOG を参照してください.