macOS + VSCode で AsciiDoc + asciidoctor + asciidoctor-diagram 環境構築

MacOS+VSCodeでAsciiDoc一式の構築記事が見当たらなかったため、書き残しておきます。

[こちらの記事](https://qiita.com/hyt126/items/fdeff36f09bb221dfac0)をMacOS+Homebrewに書き換えた形になります。
継ぎ足し継ぎ足し…秘伝のソース感も否めません。ご了承ください。

## ゴール
- Asciidocで…
    - UMLが書ける
    - HTML, PDF対応
    - VSCodeでプレビュー可能

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/286720/852b6546-8891-86bb-6df5-991b989604d4.png)


## 前提
macOS 10.15.7

### インストール済
- VSCode
- Ruby
- Homebrew
- Homebrew-cask

※ asciidoctorなどがRuby製ですのでRubyが必要になります

## インストール手順

### graphvizのインストール
graphvizはテキストから図を生成するツールです。

asciidoctor-diagramとの依存関係はなく、これがないと動かないわけではありません。
状態遷移図を書いたりする際に便利だから入れておこう、程度のもののようです。

```
brew install graphviz
```

### java8のインストール
java有償化などの問題で、`brew install --cask java8`などすることができませんので、
下記コマンドでopenjdkの8をインストールします。

```
brew tap AdoptOpenJDK/openjdk
brew install --cask adoptopenjdk8 
```

※ 昔の書き方だと`brew cask install ...`なんですが今はこの書き方。
※ [こちらの記事](https://qiita.com/d_forest/items/290bb05bb929e5d74647)参考にしております。
※ 8でないといけない理由はわかりませんが、[JDKの互換性に関してはかなり複雑そう](https://www.oracle.com/technetwork/jp/java/javase/overview/8-compatibility-guide-2156366-ja.html)ですのでおとなしく８を使っておきます。

### 各種gemのインストール

下記を一発叩きます。

```
sudo gem install bundler
sudo gem install asciidoctor
sudo gem install asciidoctor-pdf --pre
sudo gem install asciidoctor-pdf-cjk
sudo gem install asciidoctor-diagram
sudo gem install coderay
sudo gem install rouge
sudo gem install concurrent-ruby
```

※ coderay, rougeは文法チェック用のgemですので、なくても動くと思います。

### VSCodeの拡張機能 asciidoctor-vscode のインストール
VSCodeを開いて、以下の拡張機能を手動でインストールします。

```
# 拡張機能で検索して手動でインストールしてください。
asciidoctor-vscode
```
## VSCodeの設定
VSCodeの設定を開きます。（VSCode上で`cmd + ,`）
以下の設定を行ってください。

1. 検索画面に`asciidoctor`と入力
2. `Asciidoc: Asciidoctor_command`の初期値を`asciidoctor -r asciidoctor-diagram`に書き換える
3. `Asciidoc: Use_asciidoctor_js`のチェックを外す（=`false`にする）

## 動かしてみる
ここまででインストールは完了です。

asciidocの基本文法を試してみましょう：
https://asciidoctor.org/docs/asciidoc-article/

UMLは以下からサンプルをコピーして試せます：
https://asciidoctor.org/docs/asciidoctor-diagram/

``` sample.adoc
[ditaa]
....
                   +-------------+
                   | Asciidoctor |-------+
                   |   diagram   |       |
                   +-------------+       | PNG out
                       ^                 |
                       | ditaa in        |
                       |                 v
 +--------+   +--------+----+    /---------------\
 |        | --+ Asciidoctor +--> |               |
 |  Text  |   +-------------+    |   Beautiful   |
 |Document|   |   !magic!   |    |    Output     |
 |     {d}|   |             |    |               |
 +---+----+   +-------------+    \---------------/
     :                                   ^
     |          Lots of work             |
     +-----------------------------------+
....

[plantuml, diagram-classes, png]     
....
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
....
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/286720/aaba12ee-0dd4-e833-a194-d4ea08ad46f3.png)

**動かない場合はVSCodeの再起動を試してみてください。**

## 以上です✨🍰✨
皆さんのググる時間が少しでも減れば幸いです！