MacでAsciiDoc環境を構築した時のメモ。簡単にできると思いきや、思いの外時間がかかったので自分用に。
前提条件と動作環境
前提条件
- Homebrewがインストールされていること
- Node.jsがインストールされていること
- Javaがインストールされていること
動作環境
- macOS HighSierra 10.13.6
- ruby 2.3.7
- Java openjdk version “12.0.1”
- node v12.1.0
- npm 6.9.0
やりたいこと
以下のサイトを参考に、AsciiDoc & PlantUMLでテキストベースでUMLを記述し、PDFに出力する環境を構築する。
また、エディタはAtomを使っているのでAsciiDoc用のAtom環境も整える。
参考AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ
- AsciiDocで基本的なマークアップ環境を整える
- asciidoctor-pdfでPDFエクスポート環境を整える
- mermaid.jsでUML環境を整える①
- PlantUMLでUML環境を整える②
- AtomにAsciiDoc関連のパッケージを追加
AsciiDocもろもろのインストール
AsciiDoc関連のgemのインストール
|
1 2 3 |
$ sudo gem install asciidoctor $ sudo gem install asciidoctor-diagram $ sudo gem install --pre asciidoctor-pdf |
トラシューしてて必要だと判明したもの。
|
1 |
$ sudo gem install coderay |
npmでmermaid関連のライブラリをインストール
|
1 2 3 |
$ npm install -g phantomjs $ npm install -g phantomjs-prebuilt <=npm install phantomjsだとWARNINGが出たのでこいつも入れてみた $ npm install -g mermaid |
トラシューしてて必要だと判明したもの。
|
1 |
$ npm install -g mermaid.cli |
Atomにパッケージをインストール
インストールするパッケージは以下の２つ。
- language-asciidoc ··· AtomをAsciiDocに対応させる
- asciidoc-preview ··· リアルタイムプレビューできるようにする。command + shift + a でプレビュー
実行方法
HTML出力
|
1 |
$ asciidoctor sample.adoc |
PDF出力
|
1 |
$ asciidoctor-pdf sample.adoc -n -a toc -r asciidoctor-diagram -o sample.pdf |
| オプション | 説明 |
|---|---|
| -n | HTMLのh1,h2,h3···に対して自動採番する。デフォルト無効。 |
| -a | いまいちようわからん。これをつけないとtocが失敗する。 |
| toc | 目次を生成。 |
| -r | asciidoctor-pdf-cjkやasciidoctor-diagramを使う場合につけるオプション。 |
| -o | 出力ファイルを指定。デフォルトは入力ファイル（.adoc）と同じディレクトリ。 |
トラブルシューティング
Javaのruntimeが無いよエラー
問題
|
1 2 3 4 |
$ asciidoctor-pdf sample.adoc -n -a toc -r asciidoctor-diagram -o sample.pdf asciidoctor-diagram: ERROR: Failed to generate image: java_home failed: Unable to find any JVMs matching version "(null)". No Java runtime present, try --request to install. $ |
対策
Javaがインストールされていなかった。。。前提事項に書いておきながら忘れてた。ということで、下記サイトを参考にインストール。
参考https://qiita.com/y__ueda/items/049009c38068b1cea4a1
参考https://qiita.com/ringo/items/db58b34dc02a941b297f
asciidoctor-diagramでイメージ生成エラー
問題
|
1 2 |
$ asciidoctor-pdf sample.adoc -n -a toc -r asciidoctor-diagram -o sample.pdf asciidoctor-diagram: ERROR: Failed to generate image: Could not find the 'mermaid' executable in PATH; add it to the PATH or specify its location using the 'mermaid' document attribute |
対策
mermaid.cliのインストールが足りていなかった模様。
|
1 |
npm install -g mermaid.cli |
ソースコードハイライター（今回はcoderay）が無いよエラー
問題
|
1 2 3 4 5 |
$ asciidoctor-pdf sample.adoc -n -a toc -r asciidoctor-diagram -o sample.pdf asciidoctor: WARNING: optional gem 'coderay' is not available. Functionality disabled. asciidoctor: FAILED: required gem 'coderay' is not available. Processing aborted. Use --trace for backtrace $ |
対策
coderayがインストールされていなかった。最初、普通にgem installしてもなぜかうまくインストールできなかったが、２回目やったらできた。（ただの勘違い？？）
一部のサイトではrbenv gem installとしないとダメってのもあったが、rbenvが入ってなかったのでなんか適当に粘ったらできた；
|
1 |
sudo gem install coderay |
PlantUMLで謎のpngを出力してエラー
問題
以下のようなpngを出力してPlantUMLがエラーになってた。（標準エラーに出ず、PDFファイルの中身をみたらUMLが描画されておらず下記エラー画像に置き換わってる。）
|
1 2 3 |
Dot Executable :/opt/local/bin/dot File does not exist Cannot find Graphviz. |
対策
言われた通りGraphvizなるものとインストールする。Homebrewでできるらしい。
Graphvizがなにものかはググればわかる。（Wikipediaに記事がある）
|
1 |
brew install graphviz |
AtomのプレビューがずっとLoading AsciiDocのまま
問題
以下のようにAtomのプレビュー画面のまま固まってしまう。
対策
Atomの 環境設定 ＞ コア設定 と進み、「Use Tree Sitter Parser」のチェックボックスを外す。
Tree Sitter Parserとは言語の構文ツリー解析のこと。パッケージに互換性が無いためとのこと。
他の言語で構文解析ツリーを有効化したい場合はいちいち環境設定で変更する必要がある。
