# 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拡張機能をインストールする。

1. `Control`+`Shift`+`X` を押下 (または下図左下のアイコンをクリック)

2. 拡張機能の検索窓に AsciiDoc と入力

3. 下図のアイコンのAsciiDocを選択して Install をクリック

図 1. AsciiDoc拡張

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

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

1. `Control`+`Shift`+`X` を押下

2. 拡張機能の検索窓に Japanese と入力

3. "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を再起動

### 1.4. 確認方法

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

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

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

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

1. Asciidoctor.js Live Preview を開く

2. chromeに追加 ボタンを選択

3. Chromeのウィンドウ その他のツール(右上の縦3点リーダ) 拡張機能を選択

4. Asciidoctor.js Live Previewの `詳細`を選択。OFFならONに変更

5. ファイルURLへのアクセスを許可するを`有効`に

6. `拡張機能のオプション`を選択して以下を設定

   1. toc=left (目次を右につける)

   2. Enable the diagrams extension (UMLを使う)

### 2.2. 確認方法

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

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

### 3.1. HTML出力

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

1. .adocファイルを開く

2. `Control`+`Shift`+`p`を押下

3. > の横に "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 のインストールも必要。

以上