AsciiDocのインストールまとめ 2020/2/4

概要

もっとも簡単な方法を説明する。
Asciidocの記述およびPlantUML記述可能になります。
おそらくVisualStudioCodeのインストール含めて５分程度で完了するでしょう。

外部に漏れてはいけないUML図を使用しないでください
PlantUMLの記述を行った場合に外部のサーバー https://kroki.io へアクセスしてレンダリングされてしまいます。
(kiroki.io: 各種ダイアグラムをレンダリングするOSSサービスサイトです)

1. VisualStudioCodeへのインストール

1.1. VSCode自身のインストール

省略します

1.2. AsciiDoc拡張機能のインストール

VSCodeにAsciiDoc拡張機能をインストールする

拡張機能を開いて、[AsciiDoc]で検索
下図のアイコンのAsciiDocを選択して Installをクリックする（これだけ）

図 1. ADoc拡張

1.3. 初期設定の変更箇所

AsciiDocの初期パラメータを調整

メニューからFile Preference Settingを選択
Search Strings に AsciiDoc と入力。AsciiDoc関連のパラメータが表示されるので以下のパラメータを変更する
1. asciidoc preview.useEditorStyle:false (プレビューの背景を白)
2. asciidoc use_kroki: true （UML図が描画できる、ただし外部サーバー)
3. asciidoc use_asciidoctor_js: true （ここは固定である）
4. asciidoc use_asciidoctorpdf: false（ここは固定である）

★念のためvscodeを再起動

1.4. 確認方法

添付の SampleADocAndUML.adoc の表示結果が SampleADocAndUML.html の表示出力結果と同じかどうか確認してください（チェット違うけどね…)
vscodeでSampleADocAndUML.adocを開き、Cntl+K、 Cntlを離してV でプレビュー表示される

2. Chromeブラウザへのインストール(ブラウズ専用)

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

Asciidoctor.js Live Preview を開く
chromeに追加 ボタンを選択
Chrome その他ツール 拡張機能を選択
Asciidoctor.js Live Preview内の 詳細を選択。OFFならONにする
ファイルURLへのアクセスを許可するを有効にします
拡張機能のオプションを選択して以下を設定する（こんなけ）
1. toc=left (目次を右につける)
2. Enable the diagrams extension (UMLを使う)

2.1. 確認方法

vscodeと同じデータで確認を。

3. 以下古いもの（もうやらなくてよい。うまく動かない）

AsciiDocをPlantUML,Mermaid.jsを含めてインストールするものを説明する

javaのインストール ( for PlantUML)
node.jsのインストール (v10.16.0 ok)

rubyのインストール

https://rubyinstaller.org/downloads/
Ruby 2.6.3-1 (x64)
		1 - 'MSYS2 base installation'でインスト　に何度も失敗
		※１０回ぐらいで成功（msys2-x86_64-20180531.exe）

asciidoctor/diagram/pahtomjs/mermaid/mermaid.cliのインストール

コマンドラインで以下を実行する
	gem install asciidoctor
	gem install asciidoctor-diagram
	gem install --pre asciidoctor-pdf
	---
	npm install -g phantomjs
	npm install -g mermaid
	npm install -g mermaid.cli

vs code 拡張機能: joaompinto.asciidoctor-vscode

インストール

拡張機能タブから、"AsciiDoc"を検索してインストールする。
以下でもよい:
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter:
ext install joaompinto.asciidoctor-vscode

ショートカット

Toggle Preview - ctrl+shift+v (Mac: cmd+shift+v)
Open Preview to the Side - ctrl+k v (Mac: cmd+k v)
View symbols - go to symbol action - ctrl+shift+o, select a heading.

vscodeの追加設定

PlantUML,mermaid.jsをプレビューするには以下の設定を行う

"asciidoc.asciidoctor_command":"asciidoctor -a outdir=tmp -a imagesdir=tmp -a imagesoutdir=tmp -r asciidoctor-diagram -o-"
"asciidoc.use_asciidoctor_js": false

★ mermaidプレビュー不正の確認と修正

marmaidの表示でpantomjs(chronimun)を利用するが、描画できないときがある。以下のようなメッセージ：

Failed to generate image: C:\Users\<UserID>\AppData\Roaming\npm/mmdc.CMD failed: (node:6884) UnhandledPromiseRejectionWarning: Error: Failed to launch chrome!
TROUBLESHOOTING: https://github.com/GoogleChrome/puppeteer/blob/master/docs/troubleshooting.md

chromeとの非互換がある様子。 TROUBLESHOOTINGより、以下：

    const browser = await puppeteer.launch({
      ignoreDefaultArgs: ['--disable-extensions'],
    });

mermaidの起動を変更するには、mmdcコマンドに上記のオプションを追加して起動が必要。configファイルを作成して呼び出す(2step)
C:\Users\<UserID>\AppData\Roaming\npm\node_modules\mermaid.cli\node_modules\puppeteer\readme.md を参考にmmdcの起動オプションを追加する

場所は、C:\Users\<UserID>\AppData\Roaming\npm　直下

puppeteerのconfigファイルを作成
p-config.json:

    {
      "ignoreDefaultArgs": ["--disable-extensions"]
    }

mmdc.cmdファイルに追記

mmdc.cmd:

@SET CONF_OPT=-p "%~dp0\p-config.json"
@IF EXIST "%~dp0\node.exe" (
  "%~dp0\node.exe"  "%~dp0\node_modules\mermaid.cli\index.bundle.js" %CONF_OPT% %*
) ELSE (
  @SETLOCAL
  @SET PATHEXT=%PATHEXT:;.JS;=;%
  node  "%~dp0\node_modules\mermaid.cli\index.bundle.js" %CONF_OPT% %*
)

テスト

以下でpngファイルが作成できればOK
mmdc -i <mmdファイル> -o test.png

4. AsciiDocの使い方

…

5. もう一度インストール確認 2019/12/17

https://qiita.com/shiro01/items/fb93e91a8424e1c4a556

https://qiita.com/shiro01/items/a300b6d5b572a314ce5e

https://qiita.com/hyt126/items/fdeff36f09bb221dfac0

asciidoctor-pdfで日本語が化ける件は以下です https://qiita.com/hidao/items/f8a94a9ced332606c67f

C:\Ruby26-x64\lib\ruby\gems\2.6.0\gems\asciidoctor-pdf-1.5.0.beta.8\data\themes default-with-fallback-font-theme.yml の内容を default-theme.yml に転記すればよい。

■MacBookAirのバージョンを再インストールしたら動いた ★javaのネットワークアクセスが関係している様子。

>gem list ascii* * LOCAL GEMS * Ascii85 (1.0.3) asciidoctor (2.0.10) asciidoctor-diagram (1.5.18) asciidoctor-pdf (1.5.0.alpha.18) asciidoctor-pdf-cjk (0.1.3)

gem unistall 管理者権限で

gem unistall asciidoctor -v '2.0.10' のようにバージョンを指定してアンインストールする

gem install 管理者権限でバージョンを指定する

gem install asciidoctor -v '2.0.10' gem install asciidoctor-diagram -v '1.5.18' gem install asciidoctor-pdf -v '1.5.0.alpha.18' gem install asciidoctor-pdf-cjk -v '0.1.3'

もう一度最新版をインストールする →　結局だめ、UMLがあるとなぜか止まる

	最新版は以下：
	asciidoctor (2.0.10)
	asciidoctor-diagram (2.0.0)
	asciidoctor-pdf (1.5.0.beta.8)
	asciidoctor-pdf-cjk (0.1.3)
　　おそらく「asciidoctor-pdf (1.5.0.beta.8)」がおかしい
　
→　MacbookAirと同じバージョンをインストールしておわり。

asciidoctor-pdf -r asciidoctor-pdf-cjk -r asciidoctor-diagram sample.adoc

Graphvizのインストールは必要です。パスの設定も

もうしんどいから、見ない。。。（END)