Asciidoctor.jsでプレビューしながら編集する

AsciiDoc の処理系といえば、Ruby の Asciidoctor¹が有名です。しかし、JavaScript な Asciidoctor.js²もあります。本記事は後者を使ってみた記録です。

関連

• https://qiita.com/Yamane@github/items/090973185791c174532f : ブラウザで生成結果を見つつ、AsciiDoc 文書を編集できます。反映までの時間が短かく、快適に編集できます。
• https://qiita.com/dbgso/items/927c4e3d0f739855f8d6 : こちらは Ruby 版の Asciidoctor を使っています。Docker で手軽に使い始められるところが良いですね。

バージョン

$asciidoctor -vAsciidoctor 2.0.10 [https://asciidoctor.org]
Runtime Environment (ruby 2.7.1p83 (2020-03-31 revision a0c7c23c9c) [x86_64-darwin19]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

$npm -v6.14.8

きっかけ

Ruby 版の Asciidoctor には監視機能がありません。つまり、AsciiDoc ファイルに変更があった際、自動的に変換処理が行われるようにするオプションを、asciidoctorコマンドに指定することはできません。

$asciidoctor --watch main.adoc # こうできたらいいなぁ……

監視機能を進めると、プレビュー機能になります。ここでのプレビュー機能とは、生成結果が変更されたタイミングでその表示に反映されることです。HTML ファイルの場合、ブラウザで再読込する手間が省けます。

今回は HTML ファイルを生成し、プレビューすることを考えます。

Ruby 版 Asciidoctor で

Editing AsciiDoc with Live Preview³に紹介されていますが、Firefox 79.0 (64bit) では拡張機能が使えなくなっているようです。ただ、guardという gem⁴は AsciiDoc から HTML への変換過程で使えそう。

asciidoctor, guard, guard-shellをインストールします。

$bundle init
$bundle add asciidoctor guard guard-shell

main.adocという AsciiDoc ファイルを監視します。

require'asciidoctor'guard:shelldowatch('main.adoc'){|m|Asciidoctor.convert_filem[0]}end

Guard を起動します。

$guard

AsciiDoc ファイルに変更があるたびに、HTML ファイルが更新されるようになりました。

live-server登場

npm にlive-server⁵というパッケージがあり、これでプレビューを実現できます。使い方は簡単。

$live-server

guard周りでもできそうですが、これが明快かと思います。

Asciidoctor.js で

live-serverで視点が変わりました。監視はnpm-watch⁶に任せましょう。

$npm i -D asciidoctor live-server npm-watch

package.jsonに npm scripts⁷を書きます。

{"watch":{"convert":"main.adoc"},"scripts":{"start":"live-server","watch":"npm-watch","convert":"asciidoctor main.adoc"},"devDependencies":{"asciidoctor":"^2.2.0","live-server":"^1.2.1","npm-watch":"^0.7.0"}}

注意：$ npm run convertで起動される Asciidoctor は Asciidoctor.js の方です。実際、$ npx asciidoctor --helpで Asciidoctor.js のヘルプが表示されます。

AsciiDoc ファイルも準備しましょう。

= Hello

* ワン
* ツー
* スリー

用意するファイルはこれだけ：

$ls-1main.adoc
package.json

監視、プレビュー……

$npm run watch # terminal 1$npm run start # terminal 2$vim main.adoc # terminal 3

そして編集……

= Hello

_Happy AsciiDocing!_