AsciiDocのインストールまとめ rev3 [2020/12/25]

概要

AsciiDocの編集及びプレビュー表示を可能にする環境の構築方法について記述する。
情報は、2020/5/18現在のものとする。

1. Visual Studio Code上での編集/プレビュー環境構築

1.1. VSCode自身のインストール

ココ (VSCodeのサイト) からダウンロード、インストールする。


	ダウンロードページには、User InstallerとSystem Installerとが用意されているが、それぞれ以下の通り。 User Installer：そのユーザーのみにインストール System Installer：全ユーザーにインストール(管理者権限が必要) どちらを選んでもアプリケーションそのものの違いはない。

1.2. 拡張機能のインストール

1.2.1. AsciiDoc

VSCodeにAsciiDoc拡張機能をインストールする。

Control+Shift+X を押下 (または下図左下のアイコンをクリック)
拡張機能の検索窓に AsciiDoc と入力
下図のアイコンのAsciiDocを選択して Install をクリック

図 1. AsciiDoc拡張

1.2.2. VSCodeの日本語化 (※任意)

VSCodeのメニューを日本語にする。AsciiDocに直接の関係はないので任意。

Control+Shift+X を押下
拡張機能の検索窓に Japanese と入力
"Japanese Language Pack for Visual Studio Code"(発行者:Microsoft) を選択して Install をクリック

1.3. 初期設定の変更箇所

AsciiDocの初期パラメータを調整する。
※日本語化していたら、適宜読み替えのこと。

Control+, を押下 (または、メニューからFile Preference Settingを選択)
Search Strings に AsciiDoc と入力。AsciiDoc関連のパラメータが表示されるので以下のパラメータを変更
1. asciidoc preview: Use Editor Style: チェックOFF (プレビューの背景を白)
2. asciidoc Use_kroki: チェックON（UML図が描画できる、ただし外部サーバーに接続される)
3. asciidoc Use_asciidoctor_js: チェックON
4. asciidoc Use_asciidoctorpdf: チェックOFF
本設定を行ったタブを閉じた後、VSCodeを再起動

添付の SampleADocAndUML.adoc のプレビュー表示結果が SampleADocAndUML.html の表示出力結果と(ほぼ)同じかどうか確認する。
プレビューは、VSCodeでSampleADocAndUML.adocを開いた後、『Cntl+K、 Cntlを離してV』または『ウインドウ右上のアイコン IconPreview を押下』すると、右側に表示される。

2. Chrome上でのプレビュー環境構築

2.1. 拡張機能のインストール

ChromeにAsciiDoc拡張機能(Asciidoctor.js Live Preview)をインストールする。

Asciidoctor.js Live Preview を開く
chromeに追加 ボタンを選択
Chromeのウィンドウ その他のツール(右上の縦3点リーダ) 拡張機能を選択
Asciidoctor.js Live Previewの 詳細を選択。OFFならONに変更
ファイルURLへのアクセスを許可するを有効に
拡張機能のオプションを選択して以下を設定
1. toc=left (目次を右につける)
2. Enable the diagrams extension (UMLを使う)

2.2. 確認方法

添付の SampleADocAndUML.adoc をChrome上にドラッグ&ドロップして表示されるプレビュー結果が SampleADocAndUML.html の表示出力結果と(ほぼ)同じかどうか確認する。

3. 別形式でのファイル出力

3.1. HTML出力

開いている.adocファイルと同じフォルダに、同名の.htmlファイルとして保存する。上書き保存されるので注意。

.adocファイルを開く
Control+Shift+pを押下
> の横に "AsciiDoc: Save HTML document" と入力、Enterを押下

4. その他

詳細は割愛した事項を以下に記す。

4.1. PDF出力

AsciiDoctorが必要。また、AsciiDoctorをインストールするには、Rubyが必要 (gemパッケージとして配布されているため)。

AsciiDoctorをインストールするには、Rubyをインストールした後、以下のコマンドでOK。
```
gem install asciidoctor
gem install asciidoctor-pdf
```
出力するには、VSCodeの設定で asciidoc Use_asciidoctorpdf: false とした後、Control+Shift+p → "AsciiDoc: Export document as PDF" とすれば保存できる。

ただし、日本語が化けるので、default-themes.yml にフォントの情報を追記しなければならない。

4.2. PlantUML

VSCodeの拡張機能における設定で、asciidoc use_kroki: true とした場合、 PlantUMLの記述を行うと、レンダリングのため https://kroki.io にアクセスしてしまう。そのため、外部に漏れてはいけないUML図を記述できない。

ローカルでレンダリングする(外部に接続しないようにする)には、次のようにすればよい。

asciidoctor-diagramをインストール。
```
gem install asciidoctor-diagram
```

VSCodeの設定を次のように変更。

"asciidoc.asciidoctor_command":"asciidoctor -r asciidoctor-diagram"
"asciidoc.use_asciidoctor_js": false

ただし、これだと.adocと同じ場所に画像ファイルが沢山できてしまうので、

"asciidoctor -r asciidoctor-diagram -a outdir=.asciidoctor -a imagesdir=.asciidoctor -a imagesoutdir=.asciidoctor"

のようにしておくとよい。

また、諸々のUML図を描画するなら、おそらく Graphviz のインストールも必要。

以上