:icons: font = AsciiDocのインストールまとめ [small]#2020/2/4# :sectnums: :sectnumlevels: 5 :experimental: // // :module: モジュール名 // :Author: 著者名 // :Email: メールアドレス // :Date: 日付(2020/01/20) // :Revision: Rev.1 // :lang: ja // :doctype: book // :description: // :docname: ドキュメント名 // // 見出し設定 // :sectnums: // :chapter-label: // // 目次作成 :toc: left // :toclevels: 3 // // ラベルの日本語設定 // :toc-title: 目次 // :preface-title: はじめに/まえがき // :appendix-caption: 付録 // :caution-caption: 注意 // :example-caption: 例 :figure-caption: 図 // :important-caption: 重要 // :last-update-label: 最終更新 // :listing-caption: リスト // :manname-title: 名前 // :note-caption: 注記 // :table-caption: 表 // :tip-caption: ヒント // :toc-title: 目次 // :untitled-label: 無題 // :version-label: バージョン // :warning-caption: 警告 .[big]#概要# [%hardbreaks] もっとも簡単な方法を説明する。 Asciidocの記述およびPlantUML記述可能になります。 おそらくVisualStudioCodeのインストール含めて５分程度で完了するでしょう。 [IMPORTANT] -- [%hardbreaks] [yellow-background]## 外部に漏れてはいけないUML図を使用しないでください ## PlantUMLの記述を行った場合に外部のサーバー https://kroki.io へアクセスしてレンダリングされてしまいます。 (kiroki.io: 各種ダイアグラムをレンダリングするOSSサービスサイトです) -- == VisualStudioCodeへのインストール === VSCode自身のインストール https://code.visualstudio.com[省略します] === AsciiDoc拡張機能のインストール VSCodeにAsciiDoc拡張機能をインストールする . 拡張機能を開いて、[AsciiDoc]で検索 . 下図のアイコンのAsciiDocを選択して kbd:[Install]をクリックする （これだけ） image::instAsciiDocExtend.JPG[instExtADoc,700,700,title=ADoc拡張] === 初期設定の変更箇所 [%hardbreaks] AsciiDocの初期パラメータを調整 * メニューからmenu:File[Preference,Setting]を選択 * `Search Strings` に `AsciiDoc` と入力。AsciiDoc関連のパラメータが表示されるので以下のパラメータを変更する 1. menu:asciidoc[preview.useEditorStyle]:false (プレビューの背景を白) 2. menu:asciidoc[use_kroki]: true （UML図が描画できる、ただし外部サーバー) 3. menu:asciidoc[use_asciidoctor_js]: true （ここは固定である） 4. menu:asciidoc[use_asciidoctorpdf]: false（ここは固定である） ★念のためvscodeを再起動 === 確認方法 * 添付の `SampleADocAndUML.adoc` の表示結果が `SampleADocAndUML.html` の表示出力結果と同じかどうか確認してください （チェット違うけどね...) * vscodeで``SampleADocAndUML.adoc``を開き、kbd:[Cntl+K]、 kbd:[Cntl]を離してkbd:[V] でプレビュー表示される == Chromeブラウザへのインストール(ブラウズ専用) ChromeにAsciiDoc拡張機能(Asciidoctor.js Live Preview)をインストールする 1. https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia[Asciidoctor.js Live Preview] を開く 2. btn:[chromeに追加] ボタンを選択 3. menu:Chrome[その他ツール,拡張機能]を選択 4. btn:[Asciidoctor.js Live Preview]内の kbd:[詳細]を選択。OFFならONにする 5. ファイルURLへのアクセスを許可するをkbd:[有効]にします + image::instChromeAsciiDoc.jpg[a,600,100,align=center] 6. kbd:[拡張機能のオプション]を選択して以下を設定する（こんなけ） [number] .. toc=left (目次を右につける) .. Enable the diagrams extension (UMLを使う) + image::ex1.jpg[a,400,100,align=center] image::ex2.jpg[a,400,100,align=center] === 確認方法 * vscodeと同じデータで確認を。 == 以下古いもの （もうやらなくてよい。うまく動かない） 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をプレビューするには以下の設定を行う [source,json] .... "asciidoc.asciidoctor_command":"asciidoctor -a outdir=tmp -a imagesdir=tmp -a imagesoutdir=tmp -r asciidoctor-diagram -o-" "asciidoc.use_asciidoctor_js": false .... CAUTION: ★ mermaidプレビュー不正の確認と修正 marmaidの表示でpantomjs(chronimun)を利用するが、描画できないときがある。以下のようなメッセージ： ---- Failed to generate image: C:\Users\\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\\AppData\Roaming\npm\node_modules\mermaid.cli\node_modules\puppeteer\readme.md を参考にmmdcの起動オプションを追加する 場所は、C:\Users\\AppData\Roaming\npm　直下 . puppeteerのconfigファイルを作成 + p-config.json: + [source,json] ---- { "ignoreDefaultArgs": ["--disable-extensions"] } ---- . mmdc.cmdファイルに追記 + mmdc.cmd: [source] ---- @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 -o test.png == AsciiDocの使い方 == ... == もう一度インストール確認 [small]#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)