Edited at

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

More than 1 year has passed since last update.

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 を再起動すれば,プレビュー機能も問題なく動作するはず.