Developer's Blog
開発その他

AsciiDoc を手軽にプレビューする方法


こんにちは、エンジニアの宇佐見です。

私の普段の仕事では、多くの時間をソフトウェアの設計やコードの読み書きで過ごしています。しかし、ときには仕様書や報告書のように体裁が整った文書をつくる場合もあります。私はそういった文書を書くときにも、コードを書くときと同じように、プレーンテキストで書くことが多いです。

プレーンテキストで体裁が整った文書を書くときに便利なのが、軽量マークアップ言語のひとつである AsciiDoc です。軽量マークアップ言語といえば Markdown がよく知られていますが、ここで挙げた AsciiDoc は、表形式、画像の配置指定、目次の出力、などの体裁を整える際に便利な記法がサポートされているのが特徴です。また、Asciidoctor による拡張で、各種の作図記法（blockdiag、PlantUML、Graphviz など）を文書に埋め込むことも可能です。

この記事では、AsciiDoc テキストを手軽にプレビューする方法を紹介します。

AsciiDoc の例

まずは、AsciiDoc で書かれたテキストの例を挙げます。なお、記法については AsciiDoc Syntax Quick Reference が分かりやすいです。

= AsciiDoc の例

== 文章

AsciiDoc は、表形式、画像の配置指定、といったような、
整った文書を書く際に便利な記法がサポートされているのが特徴です。

== 表形式

次のように表を書くことができます。

.テーブルのタイトル
|===
|カラム名 1 |カラム名 2 |カラム名 3

|1,1
|1,2
|1,3

|2,1
|2,2
|2,3
|===

== 画像

SVG 画像を配置する例です。

image::assets/sample.svg[align="center"]

このような AsciiDoc ファイル（拡張子は .adoc）に対して、Asciidoctor で HTML や PDF に変換して出力することができます。

なぜプレビューするのか

AsciiDoc などの軽量マークアップ言語は、変換しなくてもプレーンテキストのままで読み書きすることが容易にできます。そのため、テキストを書きながら変換結果をプレビューする、という必要性は薄いです。実際私は、普段のちょっとしたメモ書き程度のものならば、書いている途中でいちいちプレビューしません。

しかし、テキストを書きながらプレビューしたい場合もあります。体裁が整った、比較的長めの文書をつくることが目的の場合、後で体裁を整えるのは案外大変です。書きながら出力が意図通りになっているかをすぐ確認できると、作業効率が良くなります。

プレビューする方法

では、どのようにして書きながらプレビューすることができるのでしょうか。この記事では、以下の方法を紹介します。

  • 方法 (1) Atom エディタでライブプレビュー
  • 方法 (2) Web ブラウザでプレビュー
  • 方法 (3) Guard-LiveReload と Web ブラウザでライブプレビュー

方法 (1) Atom エディタでプレビュー

テキストエディタ Atom に、AsciiDoc をプレビュー表示してくれるパッケージをインストールする方法です。

以下のパッケージをインストールすれば良いです。

Atom に慣れているなら、手軽にできる方法です。Atom 上で AsciiDoc ファイルを編集すれば、すぐにプレビューに反映されます。


方法 (2) Web ブラウザでプレビュー

Web ブラウザに、AsciiDoc をレンダリング表示してくれる拡張機能をインストールする方法です。

以下の拡張機能をインストールすれば良いです。

AsciiDoc ファイルを Web ブラウザで開くだけでよく、手軽にできる方法です。また、この方法であれば、AsciiDoc ファイルの編集には好みのテキストエディタを使うことができます。

ただ、テキストを編集したときに自動的にリロードしてくれる機能はないようです。これを改善したい場合は、後述の方法 (3) を使います。

以下、Firefox 版で表示した例です。


方法 (3) Guard-LiveReload と Web ブラウザでライブプレビュー

方法 (2) に Guard-LiveReload を組み合わせる方法です。テキストを編集したときに自動的にリロードするようにします。

Guard は、ファイルの変更を監視してくれるコマンドラインツールです。また、LiveReload は、Web ブラウザで自動リロードを行なってくれるツールです。

まず、以下の準備をします。

  • ターミナルで guard-livereload をインストールします（gem install guard-livereload でインストール、または Bundler でインストール）。
  • Web ブラウザに LiveReload extension をインストールします。

次に、AsciiDoc ファイルと同じディレクトリに、guard の設定ファイル Guardfile を以下の内容で作成します。

guard 'livereload' do
    watch(%r{.+\.adoc})
end

そして、ファイルの監視処理を実行します。

  • ターミナルで guard コマンドを実行します。このとき、guard のログに「INFO - LiveReload is waiting for a browser to connect.」と出力されます。
  • Web ブラウザで AsciiDoc ファイルを開き、Enable LiveReload ボタンを押します。このとき、guard のログに「INFO - Browser connected.」と出力されます。


この状態で AsciiDoc ファイルを好みのテキストエディタで編集すれば、Web ブラウザで自動的にリロードされます。

応用 : AsciiDoc の変換処理をコマンドで行う

上記の方法では、AsciiDoc ファイルを直接 Web ブラウザで自動リロードしました。少し応用すると、AsciiDoc から HTML への変換をコマンドで行い、変換後の HTML を Web ブラウザで自動リロードすることもできます。

guard-livereload に加えて、guard-shell をインストールし、Guardfile を以下のようにすれば良いです。

guard 'shell' do
    watch(%r{.+\.adoc}) do |m|
        `asciidoctor #{m[0]}`
    end
end

guard 'livereload' do
    watch(%r{.+\.html})
end

こうすることで、変換処理を自前のコマンドに置き換えることが可能になります。Web ブラウザで HTML ファイルを開き、LiveReload を使えばコマンドで変換された結果が自動的にリロードされます。

最後に

AsciiDoc を扱ったことがある方なら、Atom エディタを使う方法はご存知だったかもしれません。しかし、Web ブラウザでプレビューすることで、好みのテキストエディタで AsciiDoc を書くことができます。

また、AsciiDoc を扱ったことがない方は、ぜひ AsciiDoc を試してみてほしいと思います。

フェンリルのオフィシャル Twitter アカウントでは、フェンリルプロダクトの最新情報などをつぶやいています。よろしければフォローしてください！


関連記事

宇佐見 │

Copyright © 2019 Fenrir Inc. All rights reserved.