シナプス技術者ブログ

シナプスの技術者公式ブログ。インターネットで、鹿児島の毎日を笑顔にします。

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のインストール

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

    f:id:mkuratsubo:20190527100647p:plain
    chocolatey install

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

    f:id:mkuratsubo:20190527100713p:plain
    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の設定

  1. Visual Studio Codeを起動し、「ファイル > 基本設定 > 設定」をクリック
  2. 検索ボックスに「asciidoctor」を入力
  3. 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を指定している理由は、未設定の場合、ファイルと同一フォルダにプレビュー時に利用する画像が生成されるためです。

プレビュー

  1. 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
     ----
    
  2. Include.adocファイルを新規作成します。

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

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

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

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

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

f:id:mkuratsubo:20190527111056p:plain
GitLab