Windows上のVisual Studio Codeで、AsciiDocのプレビュー環境の構築

シナプスの技術部システム開発課の蔵坪と申します。

弊社は、10年近くソースコードは、Subversionで管理しておりましたが、昨年、GitLabに移行しました。

弊社でお世話になっているパートナーさんから、GitLabはAsciiDocが利用できるので、仕様書などのドキュメントは、AsciiDocがお勧めだとアドバイスをもらいました。そこで、Windows上のVisual Studio CodeでAsciiDocのプレビューできる環境を構築してみました。

AsciiDocとは

AsciiDocとは、メモ、ドキュメンテーション、記事、本、電子ブック、スライドショー、Webページ、マニュアルページ、ブログを書くためのテキスト文書フォーマットです。

試した環境

OS : Windows 10 Professional (1809)

AsciiDocのプレビューに必要なツール

Chocolatey
- Windows上で動作するパッケージマネージャ、こちらはなくてもいいのですが、構築が楽になります。
Visual Studio Code
- Microsoft社が公開しているオープンソースのテキストエディタ
Graphviz
- オープンソースのグラフ可視化ソフトウェア
Amazon Corretto
- アマゾンが提供している無料の OpenJDK ディストリビューション
Ruby(最新)
Asciidoctor
- AsciiDoc で書かれたコンテンツをHTML5、DocBook、 PDFなどのフォーマットに変換するオープンソースのツールです。
Asciidoctor-Diagram
- Asciidoctor Diagramは、PlantUML等のプレーンテキストを使用して記述した図をAsciiDoc文書に追加できるようにするAsciidoctor拡張機能です。

手順

Chocolateyのインストール

サイトにアクセスし、インストールコマンドをコピーします。

chocolatey install
コマンドプロンプト(管理者として実行)で、コピーしたコマンドを実行します。

chocolatey install

各種アプリケーションのインストール

コマンドプロンプト(管理者として実行)

  choco install ruby -y
  choco install vscode -y
  choco install graphviz -y
  choco install correttojdk -y

rubyのモジュールインストール

コマンドプロンプト

  gem install asciidoctor-diagram
  gem install --pre asciidoctor-pdf
  gem install asciidoctor-pdf-cjk
  gem install coderay

[Visual Studio Code]拡張機能のインストール

コマンドプロンプト

  code --install-extension joaompinto.asciidoctor-vscode
  code --install-extension ms-ceintl.vscode-language-pack-ja

Visual Studio Codeの設定

Visual Studio Codeを起動し、「ファイル > 基本設定 > 設定」をクリック
検索ボックスに「asciidoctor」を入力
Asciidoctor_commandに下記を設定し、Use_asciidoctor.jsのチェックを外す
```
 asciidoctor -r asciidoctor-diagram -a outdir=.asciidoctor -a imagesdir=.asciidoctor -a imagesoutdir=.asciidoctor
```
[f:id:mkuratsubo:20190527094052p:plain]
vs code 設定

引数で、ディレクトリに.asciidoctorを指定している理由は、未設定の場合、ファイルと同一フォルダにプレビュー時に利用する画像が生成されるためです。

プレビュー

Visual Studio Codeを起動し、適当なフォルダを開き、Sample.adocファイルを新規作成します。

= AsciiDocサンプル

これはAsciiDocで記載されたドキュメントです。

== 見出し1
* aaaaaaaa
* bbbbbbbb

== ソースコード

[source, javascript]
----
    Alert("AsciiDocサンプル");
----

== インクルード

include::Include.adoc[]

== ユースケース

[plantuml]
----
@startuml

:user: --> (Use case 1)
:user: -> (Use case 2)

@enduml
----

Include.adocファイルを新規作成します。

includeのテストです。

Sample.adocのタブの右にある「Open Preview to the Side」をクリックします。設定に問題がなければ、下記のように見えるはずです。

f:id:mkuratsubo:20190527094330p:plain — プレビュー

ドキュメントをGitで管理する場合

このままの設定だと、ドキュメントをプレビューするたびに、ファイルの同一階層の.asciidoctorフォルダに、一時ファイルが生成され続けますので、.gitignoreで除外設定しておいたほうがいいです。

また、拡張子adocのままGitlabにpushすれば、ブラウザでそのまま確認可能です。ただし、GitLabの設定で、PlantUMLサーバのアドレスを登録しておく必要があります。また、現在のGitLabではIncludeが動作しないようです。AsciiDocのIncludeが利用できるように開発が進んでいるようなので、もうしばらくしたら、利用できるのではないかと思っています。2020年4月現在、GitLab上でincludeも確認できるようになっています。