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 -v
Asciidoctor 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 -v
6.14.8

きっかけ

注意：下記の内容はGitHubのissueにありました．将来的に本体に実装される可能性も高いでしょう¹．

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 ファイルを監視します。

Guardfile

require 'asciidoctor'

guard :shell do
  watch('main.adoc') { |m| Asciidoctor.convert_file m[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 を書きます。

package.json

{
  "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 ファイルも準備しましょう。

main.adoc

= Hello

* ワン
* ツー
* スリー

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

$ ls -1
main.adoc
package.json

監視、プレビュー……

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

そして編集……

main.adoc

= Hello

_Happy AsciiDocing!_

ブラウザ上の表示が自動更新されました．

まとめ

本記事では Asciidoctor.js を用いて，プレビューしながら AsciiDoc 文書を編集する方法を紹介しました．
この方法の良いところは，必要となる準備が Node.js のみであることです．Ruby に関係するプログラム (e.g. asciidoctor) の準備が要りません．

もちろん，Ruby 版 Asciidoctor を使わざるをえない場合もあります（Ruby で実装した自前のプラグインがある場合など）．途中で註記したように，こちらへの変更監視機能の追加にも期待したいところです．

1. “Guard mode for asciidoctor command · Issue #182 · asciidoctor/asciidoctor,” GitHub. https://github.com/asciidoctor/asciidoctor/issues/182 (accessed Jan. 22, 2021). ↩