unified におけるプラグインまとめ
この記事では、 unified のプラグインについて、より詳細にまとめます。ここで使っている言葉は unified を使うための前準備という記事にまとめていますので、わからない言葉があれば参照してください。
unified の使い方
まず、 unified をどういうふうに使うのかを見てみましょう。
import unified from "unified";
import parser from "remark-parse";
import mdast2hast from "remark-rehype";
import compiler from "rehype-compiler";
const processor = unified()
.use(parser)
.use(mdast2hast)
.use(compiler)
.freeze()
processor
.process('# This is a title')
.then(html => console.log(html.toString())) // <h1>This is a title</h1>
これは Markdown を HTML に変換するためのコード例です。
4 つの import がありますが、最初の unified 以外はすべてプラグインです。 remark-parse は parser 、 remark-rehype は transformer 、 rehype-compiler は compiler です。
まず、 unified の関数呼び出しで processor を作成します。その名のとおり、変換の一連の処理を担うオブジェクトです。
プラグインを processor へ登録するために use を使います。ここでは import したプラグインをすべて登録しています。
freeze メソッドは processor にそれ以上プラグインを登録できなくするためのものです。事故防止に良いですね。
processor は次のメソッドを持っています。
| method | descs |
|---|---|
| parse | 登録した parser を使って文字列から構文木を生成する |
| compiler | 登録した compiler を使って構文木から文字列を生成する |
| run | 登録した transformer を使って、構文木を変形する |
| process | parse 、 run 、 compiler を呼び出し、文字列を処理する |
この節の内容は、型定義を見ると理解が進むでしょう。
unifed におけるプラグイン
これまで見てきたように unified はすべての機能をプラグインとして提供しています。parser / compiler / transformer それぞれが、プラグインとしてどのように実現されているかを見ていきましょう。
parser プラグイン
parser は processor が内部に持つ Parser プロパティを変更するものです。Parser は processor.parse メソッドの中で、関数であればそのまま、クラスであればインスタンス化してから実行します。
parser を自分で書く場合は remark-parse での実装を見るとわかりやすいでしょう。
TypeScript で書く場合は this の型指定を使って次のように書きましょう。
import { Node } from "unist";
import unified, { Processor } from "unified";
function parser(this: Processor) {
this.Parser = parse;
function parse(text: string): Node {
// 対応する言語に沿って、ここを実装してください
}
}
Node は unist で定義されている、木構造の中のノードを表す型です。
ここで紹介した方法は Parser に関数を指定する方法です。クラスを使う場合は GitHub に上げているコードを参照してください。
compiler プラグイン
parser と同様ですが、こちらは Compiler プロパティを変更することが責務です。
実際のコード例はこちらを参照してください。
transformer プラグイン
transformer プラグインは Markdown にオリジナルの記法を追加したり、目次を自動で追加したりなど、便利な使い方が可能です。
様々なことができる分、複雑なため、また別の記事で紹介します。
まとめ
既存のプラグインを使うにあたって必要な知識をまとめました。次回は transformer プラグインの作り方を紹介します。
Discussion