how_to_install_asciidoc.adoc

インストール手順を簡単に説明すると次の流れになります

1. rubyのインストール 一般的に配布されているwindows用Rubyをインストールする
   Ruby Installer for Windows or ActiveScriptRuby

2. gemのインストール

gem install asciidoctor
gem install asciidoctor-pdf --pre
gem install asciidoctor-pdf-cjk
gem install asciidoctor-diagram

1. 図に必要なGraphvizをインストールする。

choco install graphviz

Tip	choco はwindows用のパッケージマネージャ chocolatey

htmlへ変換してみる

asciidocファイルをhtmlに変換するには以下のコマンドを実行する

asciidoctor -r asciidoctor-diagram  how_to_install_asciidoc.adoc

Note	how_to_install_asciidoc.htmlが出力される

• 書式のクイックリファレンス
  

• 詳細な書式ドキュメント

pdfへ変換してみる

asciidoctor -o "how_to_install_asciidoc.pdf" `  (1)
            -a "pdf-fontsdir=_tools/fonts" ` (2)
            -a "pdf-stylesdir=pdf-style" ` (3)
            -a "pdf-style=basic-theme.yml" ` (4)
            -b pdf  -r asciidoctor-pdf ` (5)
            -d book -a "data-uri!" ` (6)
            -r asciidoctor-diagram `  (7)
            -r asciidoctor-pdf-cjk`  (8)
             "how_to_install_asciidoc.adoc"

1. 入力ファイル名

2. フォントフォルダ

3. スタイル配置フォルダ

4. PDFスタイルファイル

5. pdf出力を指定

6. 画像をdata-uriとして埋め込まない指示(定型オプション)

7. 図表の変換を指示

8. 日本語対応

Important

日本語PDFへの変換には、フォントの設定が必要です。FONT及びpdfのスタイルを使用する 日本語フォントには、 源真ゴシック及び源真ゴシック等幅を使用している。 PDFスタイルの詳細は、 こちら

日本語対応のサンプルプロジェクトをGithubに公開しました。

このプロジェクトではasciidocファイルを編集すると自動的にhtmlとpdfを出力してブラウザでリアルタイムに編集内容を確認できるようになります。

asciidoctor-pdf-live-reload-seed

インストール手順に従ってインストールするだけ、asciidoctor関連の基本ツールがインストールできます。

簡単にhtmlとpdfに変換するだけなら

./generate.ps1 README

live reloadするなら

gulp

まだまだ発展途上な部分もありますが、現在のバージョンでも十分実用に耐えるツールです。さくっとドキュメントを作ってみて、成果物の綺麗さで現場を説得してみませんか？

Note	フットノートがpdf出力時に正しく反映されない。 PDF出力時に [souce] ブロックの行番号出力を行えるフォーマッタは rouge のみ