asciidoctor.jsでJavaScriptからasciidocファイルを変換する方法

AsciiDocは、Markdownに似ている軽量マークアップ言語です。比較的マイナーですがGitHubでのプレビューに対応しています。

Markdownはドキュメント記述言語としては仕様が貧弱なため、簡潔に書くのが難しいものや、環境毎に異なる方言を使わなければならない事が多いです。
ただ、AsciiDocはそれなりに多機能な仕様が公式でしっかり定義されているので取り扱いやすい言語だと言えます。
https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/

下記はasciidocファイルのサンプルです。#が=になったMarkDownのような感じですね。

example.asciidoc

:hardbreaks:
= AsciiDocの例

== AsciiDocの例の一章 

内容です

AsciiDocにはAsciiDoctorというドキュメント変換プロジェクトがあり、これを使用してコマンドラインからasciidocファイルをHTMLに変換する方法はよく知られていますが、このAsciiDoctorをJavaScriptのコードから呼び出す方法についての日本語の解説があまり無いようだったので紹介します。

インストール

今回はnode.jsのJavascriptから変換をかける予定なのでnpmのセットアップを行います。
AsciiDoctorのjs版のasciidoctor.jsをインストールします

package.json

{
  "type": "module",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "asciidoctor": "^2.2.6"
  }
}

下記を実行してセットアップ完了です。

npm install

使用方法

冒頭に例示したasciidocファイルを変換してみます。

index.js

import Asciidoctor from 'asciidoctor';
const asciidoctor = Asciidoctor();

const doc = asciidoctor.loadFile("./example.asciidoc");
const html = doc.convert();

console.log(html);

npm run start

出力内容例

<div class="sect1">
<h2 id="_asciidocの例の一章">AsciiDocの例の一章</h2>
<div class="sectionbody">
<div class="paragraph">
<p>内容です</p>
</div>
</div>
</div>

下記の様なコマンドと同等のHTMLが生成されていますね。

npx asciidoctor -a stylesheet! -a webfonts! -b html5 --no-header-footer example.asciidoc

ドキュメントから情報を取り出す

asciidocを活用してWebページ生成したい場合、ドキュメント本体だけでなく様々な情報をドキュメントから取り出したくなる場合があると思います。
たとえば、ページのタイトルを取り出してHTMLの<title>タグに挿入したりするような場合や、筆者情報をリッチなHTMLで表示したい場合などです。
また、ページに合わせて独自の属性を定義することもできます。今回はisdraftとvolumeという属性を追加しました（下書きと章番号などを格納しているような想定です）。

example.asciidoc

:hardbreaks:
:isdraft:
:volume: 3

= AsciiDocの例
山田 太郎 <[e-mail]>

== AsciiDocの例の一章

内容です

Javascriptのコードはこのようにします。

index.js

import Asciidoctor from 'asciidoctor';
const asciidoctor = Asciidoctor();

const doc = asciidoctor.loadFile("example.asciidoc");

const title = doc.getDocumentTitle();
const isdraft = doc.getAttribute('isdraft');
const volume = doc.getAttribute('volume');
const author = doc.getAuthor();

console.log("title:", title);
console.log("isdraft:", isdraft);
console.log("volume:", volume);
console.log("author:", author);

出力例

title: AsciiDocの例
isdraft:
volume: 3
author: 山田 太郎

これらの情報とasciidocの変換結果をテンプレートエンジンに埋め込めばしっかりしたWebページを生成をできますね。

参考情報

https://docs.asciidoctor.org/asciidoctor.js/latest/processor/convert-options/
https://docs.asciidoctor.org/asciidoctor.js/latest/setup/install/