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にパッケージをインストール
インストールするパッケージは以下の2つ。
- 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
してもなぜかうまくインストールできなかったが、2回目やったらできた。(ただの勘違い??)
一部のサイトでは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とは言語の構文ツリー解析のこと。パッケージに互換性が無いためとのこと。
他の言語で構文解析ツリーを有効化したい場合はいちいち環境設定で変更する必要がある。