概要

AsciiDocの編集及びプレビュー表示を可能にする環境の構築方法について記述する。
情報は、2020/5/18現在のものとする。

1. Visual Studio Code上での編集/プレビュー環境構築

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

ココ (VSCodeのサイト) からダウンロード、インストールする。

VSCode Installer

ダウンロードページには、User InstallerとSystem Installerとが用意されているが、それぞれ以下の通り。

  • User Installer：そのユーザーのみにインストール

  • System Installer：全ユーザーにインストール(管理者権限が必要)

どちらを選んでもアプリケーションそのものの違いはない。

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

1.2.1. AsciiDoc

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

  1. Control+Shift+X を押下 (または下図左下のアイコンをクリック)

  2. 拡張機能の検索窓に AsciiDoc と入力

  3. 下図のアイコンのAsciiDocを選択して Install をクリック

instExtADoc
図 1. AsciiDoc拡張

1.2.2. VSCodeの日本語化 (※任意)

VSCodeのメニューを日本語にする。AsciiDocに直接の関係はないので任意。

  1. Control+Shift+X を押下

  2. 拡張機能の検索窓に Japanese と入力

  3. "Japanese Language Pack for Visual Studio Code"(発行者:Microsoft) を選択して Install をクリック

1.3. 初期設定の変更箇所

AsciiDocの初期パラメータを調整する。
※日本語化していたら、適宜読み替えのこと。

  • Control+, を押下 (または、メニューからFile  Preference  Settingを選択)

  • Search Strings に AsciiDoc と入力。AsciiDoc関連のパラメータが表示されるので以下のパラメータを変更

    1. asciidoc  preview: Use Editor Style: チェックOFF (プレビューの背景を白)

    2. asciidoc  Use_kroki: チェックON（UML図が描画できる、ただし外部サーバーに接続される)

    3. asciidoc  Use_asciidoctor_js: チェックON

    4. asciidoc  Use_asciidoctorpdf: チェックOFF

  • 本設定を行ったタブを閉じた後、VSCodeを再起動

1.4. 確認方法

添付の SampleADocAndUML.adoc のプレビュー表示結果が SampleADocAndUML.html の表示出力結果と(ほぼ)同じかどうか確認する。
プレビューは、VSCodeでSampleADocAndUML.adocを開いた後、『Cntl+K、 Cntlを離してV』または『ウインドウ右上のアイコンIconPreviewを押下』すると、右側に表示される。

2. Chrome上でのプレビュー環境構築

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

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

  1. Asciidoctor.js Live Preview を開く

  2. chromeに追加 ボタンを選択

  3. Chromeのウィンドウ  その他のツール(右上の縦3点リーダ)  拡張機能を選択

  4. Asciidoctor.js Live Previewの 詳細を選択。OFFならONに変更

  5. ファイルURLへのアクセスを許可するを有効に

    a

  6. 拡張機能のオプションを選択して以下を設定

    1. toc=left (目次を右につける)

    2. Enable the diagrams extension (UMLを使う)

      a
      a

2.2. 確認方法

添付の SampleADocAndUML.adoc をChrome上にドラッグ&ドロップして表示されるプレビュー結果が SampleADocAndUML.html の表示出力結果と(ほぼ)同じかどうか確認する。

3. 別形式でのファイル出力

3.1. HTML出力

開いている.adocファイルと同じフォルダに、同名の.htmlファイルとして保存する。上書き保存されるので注意。

  1. .adocファイルを開く

  2. Control+Shift+pを押下

  3. > の横に "AsciiDoc: Save HTML document" と入力、Enterを押下

4. その他

詳細は割愛した事項を以下に記す。

4.1. PDF出力

AsciiDoctorが必要。また、AsciiDoctorをインストールするには、Rubyが必要 (gemパッケージとして配布されているため)。

  • AsciiDoctorをインストールするには、Rubyをインストールした後、以下のコマンドでOK。

    gem install asciidoctor
gem install asciidoctor-pdf

  • 出力するには、VSCodeの設定で asciidoc  Use_asciidoctorpdf: false とした後、Control+Shift+p → "AsciiDoc: Export document as PDF" とすれば保存できる。

ただし、日本語が化けるので、default-themes.yml にフォントの情報を追記しなければならない。

4.2. PlantUML

VSCodeの拡張機能における設定で、asciidoc  use_kroki: true とした場合、 PlantUMLの記述を行うと、レンダリングのため https://kroki.io にアクセスしてしまう。そのため、外部に漏れてはいけないUML図を記述できない。

ローカルでレンダリングする(外部に接続しないようにする)には、次のようにすればよい。

  • asciidoctor-diagramをインストール。

    gem install asciidoctor-diagram

  • VSCodeの設定を次のように変更。

    "asciidoc.asciidoctor_command":"asciidoctor -r asciidoctor-diagram"
"asciidoc.use_asciidoctor_js": false

ただし、これだと.adocと同じ場所に画像ファイルが沢山できてしまうので、

"asciidoctor -r asciidoctor-diagram -a outdir=.asciidoctor -a imagesdir=.asciidoctor -a imagesoutdir=.asciidoctor"

のようにしておくとよい。

また、諸々のUML図を描画するなら、おそらく Graphviz のインストールも必要。

以上