remark 13移行:サブパッケージと外部プラグイン
remark 13移行に向けた、packages/ 配下のサブパッケージとVFMが依存する外部remark / rehypeプラグインの調査(Phase 0-2, #278)。remark13-migration.mdの要約を展開したもので、packages/vfm インベントリを補完する。2026-10-17時点の main を対象に調査し、上流の挙動はpnpm storeにすでにあるパッケージ(mdast-util-to-hast 13.2.1, hastscript 9.0.1, remark-rehype 11.1.2)で確認した。
変更分類はインベントリと同じ: Rewrite (仕組みが消える)、Adapt (同じ仕組みでAPIが変わる)、Keep (型の更新のみ)。
サブパッケージ
| パッケージ | バージョン | 段階 | 影響 | 変更 |
|---|---|---|---|---|
@vivliostyle/remark-ruby |
1.0.1 | 旧tokenizer + handler | 大 | Rewrite |
@vivliostyle/remark-footnote-dpub |
1.0.1 | handler ×3 + hast | 中 | Adapt (handler), Rewrite (inline noteの供給元) |
@vivliostyle/remark-footnote-gcpm |
1.0.1 | handler ×2 | 中 | Adapt (handler), Rewrite (inline noteの供給元) |
@vivliostyle/remark-footnote-pandoc |
1.0.1 | hastのみ | 中 | Rewrite (セレクターが上流出力に追従) |
@vivliostyle/remark-sectionize |
1.0.1 | mdast transformer | 小 | Adapt (型、ユーティリティのmajor) |
@vivliostyle/mdast-to-hast-table-cell |
0.0.0 | handlerラッパー | 中 | Adapt (handler署名、deep import) |
@vivliostyle/rehype-rewrite-extension |
0.0.0 | hastのみ | 小 | Keep |
@vivliostyle/vfm-internal-utils |
1.0.1 | hastscriptヘルパー | 小 | Keep |
共通する特徴:
- どのパッケージにも
exportsフィールドが無い。すべてlib/をpublishし、main/typesがコンパイル済みエントリーを指す。 mdast-util-to-hastに触れるパッケージはすべて11.3に直接依存し、同時にremark-rehype8が10.2を引き込む。handler署名とfootnoteByIdの形は11から、endnote footerの出力は10から来ている。- すべてのテスト スイートが
devDependenciesのremark-parse8オプション({ gfm: true, commonmark: true })、remark-footnotes、remark-attrで独自のプロセッサを組んでいる。テスト ユーティリティはすべてpackages/vfm/src/index.tsと同じ書き直しが必要。 - 以下は共通で、まとめて更新する:
hast-util-select5unist-builder3unist-util-visit4hastscript7@types/{hast,mdast,unist}2/3/2
remark-ruby
ソース: packages/remark-ruby/src/ruby.ts。
- パーサー
{base|ruby}用のinline tokenizerをthis.Parser.prototype.inlineTokenizers/inlineMethodsのtextの前に登録する。this.tokenizeInline(inlineContent, now)を呼んでベース テキストを再帰的にパースするため、ルビの中に強調、コード、その他のインライン記法を含められる。remark 13はこの登録を無言で無視する。
- 型
Eat、Parser、Tokenizerをremark-parseからimportしているが、それはdevDependencyにしかないため、公開している.d.tsはremark-parse無しでは利用できない。- ローカルの
Tokenizer型はremark-parse 8の型定義の欠落を補っている:this.tokenizeInlineeat.now()- 省略不可の
Point.offset
unistのDataにhNameをaugmentation。
- handler
(h, node)でh(node, 'ruby', [...all(h, node), rt])を返す。rtのテキストはdata.rubyTextで運ぶ。
- 変更
- パーサーをmicromark拡張と
mdast-util-from-markdown拡張(childrenとrubyTextを持つrubyノードを組むenter/exithandler)として書き直す。難所は入れ子のインライン パース:ベース テキストを文字列から再パースするのではなくmicromarkにパースさせるため、拡張は{…|をインライン コンテナーとしてトークン化する必要がある。 - handlerは
state.all(node)とstate.patch/state.applyDataを使う(state, node)になる。 remark-parseの型importとDataのaugmentationを削除する。
- パーサーをmicromark拡張と
- テスト
tests/ruby.test.tsはremark-parse8 +remark-breaks1 +remark-rehype8を組んでhandlerを登録する。期待値はHTML文字列なので、出力を再現できれば維持できる。
remark-footnote-dpub と remark-footnote-gcpm
ソース: packages/remark-footnote-dpub/src/index.ts、packages/remark-footnote-gcpm/src/index.ts。
両パッケージとも footnoteReference と footnote のhandlerを上書きし(dpubは footnoteDefinition も)、カスタマイズ可能な要素には @vivliostyle/vfm-internal-utils の buildElement を使う。
- handlerの状態
- handlerは
(ctx, node)で、ctx.footnoteByIdをplain objectとして読む:identifier in ctx.footnoteByIdctx.footnoteById[id]- inline noteでの代入
mdast-util-to-hast13のstate.footnoteByIdはString(identifier).toUpperCase()をキーとするMap(正規化は現在と同じ)なので、すべてのアクセスがhas/get/setになる。all(ctx, node)はstate.all(node)になる。
- handlerは
- inline note
footnotehandlerはremark-footnotesが生成するinline noteノード(^[...])を消費し、その場でfootnoteDefinitionを合成する。remark-gfm 4にinline noteは無いため、VFMのinline note拡張ができるまでこのhandlerへの入力は無い。ノード型と形はVFMが定義するものなので、handlerはその定義に対して書くべき。
- 採番
- 両パッケージはhandler呼び出し時に
refIndexを割り当て、dpubは最終のhastパスで採番し直す。これはmdast-util-to-hast< 12.1.1がtable cellを逆順に走査していたため(#129)。v13では走査順が文書順なので、採番し直しは恒等変換になり、安全網として残すか削除できる。v13の既定handlerは重複も自身で追跡する(state.footnoteCounts、-2接尾辞)が、カスタムhandlerはこれを使っていない。
- 両パッケージはhandler呼び出し時に
- hastscript
- dpubは
h('sup', u('text', '1'))を組む。hastscript 9はproperties位置に渡されたplainなtextノードをpropertiesとして扱う(isChild判定は、値が文字列だけのオブジェクトに対してfalseを返す)ため、<sup>にtype/value属性が付いてテキストが無くなる。childrenは配列で渡すか、textノードを明示的に組む。propertiesオブジェクトを明示している呼び出し(h('a', {...}, child))は影響を受けない。
- dpubは
- dpub transformer
createReplaceDpubPlaceholdersは<div data-footnote-placeholder>をキューされた<aside>で置き換え、inline noteのasideを最も近い非flow container祖先の後に挿入するhast transformer。hastとhast-util-selectにしか依存しないので、ユーティリティのmajor更新で適応できる。
- gcpm
hastTransformerはno-opで、すべてhandler内で処理する。hastTransformer: unified.Pluginは名前空間型を使う。
- 変更
- handlerを
MapAPIを使う(state, node)にAdaptする。 - inline noteノード定義に追従する。
h('sup', textNode)を修正する。unified.Pluginを名前付きPlugin型に置き換える。
- handlerを
- テスト
tests/dpub.test.tsとtests/gcpm.test.tsはremark-footnotesでプロセッサを組みHTMLを比較する。inline noteのケースには新しい拡張が必要。それ以外は維持できるはず。
remark-footnote-pandoc
ソース: packages/remark-footnote-pandoc/src/index.ts。
-
仕組み
- handlerは無い(
toHastHandlersはすべてundefined)。2つのhast transformerがmdast-util-to-hast10の出すendnoteマークアップをPandoc風の<section role="doc-endnotes">に書き換え、呼び出しを文書順で採番し直し、重複参照にバックリンクを追加する。
- handlerは無い(
-
依存
-
すべてのセレクターがv10のfooterに固定されている:
div.footnotesli[id^="fn-"]sup[id^="fnref-"]:has(a:only-child[href^="#fn-"].footnote-ref)a.footnote-backref
-
v13のfooterはセレクターが触れるすべての点で異なる:
mdast-util-to-hast10mdast-util-to-hast13Area <div class="footnotes"><section data-footnotes class="footnotes">と<h2 id="footnote-label" class="sr-only">Footnotes</h2>Element <li id="fn-ID"><li id="user-content-fn-id">Call <sup id="fnref-ID"><a href="#fn-ID" class="footnote-ref"><sup><a href="#user-content-fn-id" id="user-content-fnref-id" data-footnote-ref aria-describedby="footnote-label">Backlink <a href="#fnref-ID" class="footnote-backref"><a href="#user-content-fnref-id" data-footnote-backref class="data-footnote-backref" aria-label="Back to reference N">重複 未対応 呼び出しidに -2,-3接尾辞と追加のバックリンク -
remark-rehype11は、user-content-接頭辞とラベル見出しを除去し、バックリンクの内容を調整するオプションを公開している:clobberPrefixfootnoteLabelfootnoteLabelTagNamefootnoteLabelPropertiesfootnoteBackLabelfootnoteBackContent
-
-
変更
- セレクターと呼び出し/バックリンクの書き換えをv13のfooterに合わせて書き直すか、(推奨)既定footerの後処理をやめて、カスタムの
footnoteReference/footnoteDefinitionhandlerとstate.footnoteOrderから組むfooterでPandoc構造を直接出力する。後者は上流のマークアップ変更からパッケージを独立させる。 - v13は重複参照も文書順も処理するため、重複と採番し直しのロジックは簡略化できる。
- ローカルの
mergePluginsコピーとunified.Pluginは名前付き型に置き換える。
- セレクターと呼び出し/バックリンクの書き換えをv13のfooterに合わせて書き直すか、(推奨)既定footerの後処理をやめて、カスタムの
-
テスト
tests/pandoc.test.tsはパイプライン全体のHTMLを比較する。すべての期待値が選択する出力とclobberPrefixの決定に依存する。
remark-sectionize
ソース: packages/remark-sectionize/src/section.ts。
- 仕組み
- mdast transformer。見出しをdepth 6から1の順にvisitし、各見出しとそれに続く兄弟を
data.hName/data.hPropertiesを持つsectionノードで包む。positionのオフセットでソースから元の見出し行を読み、閉じハッシュ(## Title ##はセクション化しない)と終了マーク(##単独でセクションを閉じる)を検出する。
- mdast transformer。見出しをdepth 6から1の順にvisitし、各見出しとそれに続く兄弟を
- 依存
@types/mdast3のContentとHTML(4ではRootContentとHtml)unist-util-find-after4とunist-util-visit-parents5 (現在は5と6)vfile4のfile.toString()(6でも動く)remark-attrが{hidden}から設定するheading.data.hProperties.hidden。attrの書き直しに追従するBlockContentMapとunistのDataをaugmentation。- 残っている
node.type === 'export'の判定はMDX時代のremarkのもので、何にも一致しない。
- 変更
- 型とユーティリティのmajorをAdapt。オプトアウトと終了マークの検出はASTではなくソース テキストを読むため、閉じシーケンス付き見出しと
##単独行でmicromarkが同じpositionを与えることをPhase 4で検証する。
- 型とユーティリティのmajorをAdapt。オプトアウトと終了マークの検出はASTではなくソース テキストを読むため、閉じシーケンス付き見出しと
- テスト
tests/utils.tsは{hidden}のためにremark-attrとremark-parse8オプションを使い、rehype-formatとremark-attrを@ts-expect-error付きでimportしている。
mdast-to-hast-table-cell
ソース: packages/mdast-to-hast-table-cell/src/index.ts。
- 仕組み
withTableCellTransform(hook)(handler)がtablehandlerをラップし、実行結果からすべてのth/tdを集め、各セルをhookの出力で置き換える。hookは{ h }とセル コンテキスト(node、tagName、align、properties、children)を受け取る。3つのプリセットはalign属性を属性、class、インラインstyleのいずれかに移す。
- 依存
mdast-util-to-hast11のHとHandler型。ラッパーとhookは(h, node, parent)。cell.properties.alignを読むが、v13のtableRowhandlerもこれを設定するためセル検出は成立する。- テストが
mdast-util-to-hast/lib/handlers/table.jsをdeep importしており、v13はexportsで閉じる。v13はルートからdefaultHandlers.tableをexportする。 hast-util-get-attribute1とhast-util-get-class-list1に新しいmajorは無い。
- 変更
- ラッパーを
(state, node, parent)にAdaptし、hookにはhではなくstate(または絞った部分集合)を渡す。これは公開型TableCellHookの変更になる。 - テストのdeep importを
defaultHandlers.tableに置き換える。 rehype-format5が型を同梱したらtests/rehype-format.d.tsを削除する。
- ラッパーを
- テスト
tests/table.test.tsとtests/composition.test.tsはremark-parse8 +remark-rehype8でHTMLを比較する。13ではGFM tableはremark-gfmから来る。
rehype-rewrite-extension
ソース: packages/rehype-rewrite-extension/src/index.ts。
- 仕組み
- hast transformer。各ルールについて
hast-util-selectで要素を選び、hast-util-get-attributeでプロパティを読み、uri-js/upathでURIパスの拡張子を書き換えて書き戻す。
- hast transformer。各ルールについて
- 依存
hast-util-select5 (現在は6)。remarkやunifiedのimportは無い。
- 変更
- Keep。
hast-util-selectと@types/hastを更新する。テストは手で組んだツリーでtransformerを直接実行しており変更不要。
- Keep。
vfm-internal-utils
ソース: packages/vfm-internal-utils/src/element-customizer.ts。
- 仕組み
buildElement(tagName, props, children, customizer)がhastscriptで要素を組む。customizerは追加propertiesか、tag-awareなhを受け取るfactory。HastPropertiesSchemaはhast.Properties用のvalibotスキーマ。
- 依存
- hastscript 7の
h、Properties、Child型。すべての呼び出しが明示的なpropertiesオブジェクトを渡す(h(tagName, props, ...children))ため、hastscript 9のchild / propertiesの曖昧さはここには当たらないが、ユーザーが渡すfactoryは影響を受けうる。
- hastscript 7の
- 変更
- Keep。hastscriptを更新し、
TagAwareHのオーバーロードをhastscript 9の署名と照合する。
- Keep。hastscriptを更新し、
外部プラグイン
| プラグイン | 利用元 | 現行 | remark 13での状況 | 判断 |
|---|---|---|---|---|
| remark-attr | vfm (attr.ts), remark-sectionizeテスト |
0.11.1 | 2020年から更新停止。remark-parse 8のすべてのinline / block tokenizerをラップして {...} 属性を付加する。micromark移植は無い。 |
VFMの属性拡張を書く(#46, #211)。先行試作: origin/remark-attribute。利用側: code.ts (fenced codeの属性)、slug.ts (見出しの {#id})、remark-sectionize ({hidden})、figure.ts ({alt=...})。 |
| remark-shortcodes | vfm (toc.ts, metadata.ts) |
0.3.1 | 更新停止。Parser.prototype.blockTokenizers を書き換える。 |
[[toc]] の存廃は#207に従う。残す場合は小さなmicromark block拡張か remark-directive 4 (::toc)で置き換える。 |
| remark-footnotes | vfm (footnotes.ts), footnoteパッケージのテスト |
2.0.0 | deprecated。Parser.prototype を書き換える。remark-gfm 4は [^id] の参照と定義を提供するがinline note ^[...] は無い。 |
参照/定義にはremark-gfmを使う。footnoteパッケージが消費するノードを出すinline noteのmicromark拡張を書く。 |
| remark-breaks | vfm (line-breaks.ts), remark-rubyテスト |
1.0.5 | 4.0.0は型付きの通常のmdast transformer。 | 更新。 |
| remark-frontmatter | vfm (revive-parse.ts, metadata.ts) |
2.0.0 | 5.0.0は型付きのmicromark拡張。 | 更新。 |
| remark-math | – | – | 6.0.0 (micromark-extension-math 3.1.0, mdast-util-math 3.0.0)。value を持つ inlineMath / math ノードを出す。 |
math.ts のtokenizerを置き換える候補(#224)。ノード名と value フィールドがVFMの inlineMath / displayMath + data.value と異なる。 |
| rehype-raw | vfm, dpub / sectionize / table-cellテスト | 5.1.0 | 7.0.0 (hast-util-raw 9)。 |
更新。 |
| rehype-format | vfm (format.ts),全テスト |
3.1.0 | 5.0.1は型を同梱。 | 更新。ambient宣言を削除。 |
| rehype-stringify | vfm,全テスト | 8.0.0 | 10.0.1。 | 更新。 |
hast / unistユーティリティ
| パッケージ | 現行 | 移行先 | 利用元 |
|---|---|---|---|
| hastscript | 7.2.0 | 9.0.1 | vfm, dpub, gcpm, pandoc, vfm-internal-utils |
| hast-util-select | 5.0.5 | 6.0.4 | vfm, dpub, pandoc, rehype-rewrite-extension |
| hast-util-raw | 6.1.0 | 9.1.0 | vfm (figure.ts) |
| hast-util-from-html | 1.0.2 | 2.x | vfm (math.ts) |
| hast-util-find-and-replace | 3.2.1 | 5.x | vfm (replace.ts) |
| hast-util-is-element | 2.1.3 | 3.0.0 | vfm |
| hast-util-get-attribute / get-class-list | 1.x | 1.x | table-cell, rehype-rewrite-extension |
| unist-builder | 3.0.1 | 4.0.0 | vfm, ruby, dpub, pandoc |
| unist-util-visit | 4.1.2 | 5.1.0 | vfm, table-cell |
| unist-util-visit-parents | 5.1.3 | 6.0.2 | vfm, sectionize |
| unist-util-find-after | 4.0.1 | 5.0.0 | vfm, sectionize |
| unist-util-select | 4.0.3 | 5.1.0 | vfm |
| unist-util-remove / filter / inspect | 3 / 4 / 7 | 4 / 5 / 8 | vfm |
| mdast-util-to-string | 3.2.0 | 4.0.0 | vfm |
| mdast-util-find-and-replace | 2.2.2 | 3.x | vfm (math.ts、削除予定) |
| refractor | 3.6.0 | 5.0.0 | vfm (code.ts) |
| to-vfile / vfile | 6.1 / 4.0 | 8.0 / 6.0 | vfm, sectionize |
作業順序
- まずVFM独自のノード形状を定義する: inline note、ruby、属性の運搬役、
[[toc]](残す場合)。footnoteパッケージ、slug.ts、metadata.ts、remark-sectionizeがすべてこれらを読む。 - 共通のhast / unistユーティリティと
hastscriptを全パッケージで一括更新する。パッケージ同士がworkspace:*でimportし合っているため。 vfm-internal-utilsとrehype-rewrite-extension(Keep)、次にmdast-to-hast-table-cellとremark-sectionize(Adapt)、次にfootnoteパッケージ、最後にremark-rubyを移植する。- 各パッケージのテスト ユーティリティはパッケージと一緒に書き直す。remark-parse 8オプションと
remark-footnotes/remark-attrのdevDependenciesが残る唯一の場所になる。