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

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

こちらの記事をMacOS+Homebrewに書き換えた形になります。
継ぎ足し継ぎ足し…秘伝のソース感も否めません。ご了承ください。

ゴール

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

前提

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 ...なんですが今はこの書き方。
※ こちらの記事参考にしております。
※ 8でないといけない理由はわかりませんが、JDKの互換性に関してはかなり複雑そうですのでおとなしく８を使っておきます。

各種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
....

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

以上です✨🍰✨

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