asciidoc
VSCode

VS Code でフロントマターのある AsciiDoc を扱う

Jekyll とか Hugo とかで AsciiDoc や Markdown を書くとき,ファイルの先頭に YAML (たまに TOML) を入れることがあります.
フロントマター (front matter) と呼ばれるやつです.

---
title: hello
description: hello to the world
---

このフロントマターが入った AsciiDoc を VS Code で扱うのにいろいろ設定をしたので,ここにメモしておきます.

ちなみに,設定がうまくいったときのスクリーンショットはこんな感じです.

adoc_preview.png

AsciiDoc プラグインのインストール

まずは AsciiDoc 用のプラグインをインストールします.

Ctrl+P を押して次のコマンドを叩けば,インストールできます.

ext install joaompinto.asciidoctor-vscode

普通の AsciiDoc 文書を編集するだけなら,もうこれでシンタックスハイライトもプレビュー機能も使えるようになります.

asciidoctor のインストール

フロントマターのある AsciiDoc 文書の場合,シンタックスハイライトは特に問題ないみたいですが,プレビュー機能がうまく動かなかったりします.
例えば,次のような :source-highlighter: を指定した AsciiDoc 文書をプレビューしようとすると,エラーが出てしまいます.

---
title: hello
description: hello to the world
---

:source-highlighter: coderay

= hello

A _hello world_ program in C can be writtern as follows:

[source,c]
----
int main(void) {
    printf("hello, world\n");
    return 0;
}
----
CodeRay: uninitialized constant CodeRay

どうやら,プラグインが内部で使用している Asciidoctor.js はフロントマナーをうまく処理できないみたいなので,本家の Asciidoctor をインストールしてそれを使わせるようにします.

というわけで,Asciidoctor をインストールします.
インストールは gem で出来ます.

$ gem install asciidoctor

次のコマンドが通ったら,Asciidoctor のインストールは成功です.

$ asciidoctor --version
Asciidoctor 1.5.6.2 [http://asciidoctor.org]
Runtime Environment (ruby 2.3.1p112 (2016-04-26) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

VS Code 側の設定

[File] - [Preferences] - [Settings] を開き,以下の 2 行を追記します.

    "AsciiDoc.use_asciidoctor_js": false,
    "AsciiDoc.asciidoctor_command": "asciidoctor -a skip-front-matter",

これで VS Code を再起動すれば,プレビュー機能も問題なく動作するはず.