remark 13移行ノート
VFMのMarkdownツールチェインをremark 8 / unified 9からremark 13以降(remark-parse 11, unified 11, mdast-util-to-hast 13)へ移行するための作業ノート。Phase 0の調査結果と移行方針を記録する。進捗はGitHubで管理している。#275が統括Issueで、各Phaseにsub-issueがある。
| Phase | Issue | 範囲 |
|---|---|---|
| 0 | #276 | 現状調査と移行方針(この文書) |
| 1 | #280 | packages-next/ の足場構築 |
| 2 | #281 | 基盤ライブラリ更新(unified / vfile / mdast-util-to-hast / rehype) |
| 3 | #285 | 構文プラグインのmicromark化 |
| 4 | #293 | 互換検証とテスト移植 |
| 5 | #296 | カレント切り替えと公開 |
Phase 2と3は一部並行できる。Phase 4はPhase 3の各構文が揃うたびに部分的に進める。
移行方針
- remark 13以降のコードベースをnextと呼ぶ。
- モノレポで現行(
packages/)とnext (packages-next/)を併存させる。packages/配下に両世代を混在させると運用しにくいため、ディレクトリーを分ける。 packages-next/はpackages/をコピーしてから変更してゆく。- next系パッケージはすべて
"private": trueにして誤ってpublishされないようにし、nameに-nextを付けてpnpmの--filterとworkspace:*の解決が曖昧にならないようにする。 - 両ツリーをpnpm workspaceに含め、ルートの
pnpm build/pnpm testでビルドとテストを行う。 - nextが現行VFMの挙動を再現できたらツリーを入れ替える。
packages/→packages-old/、packages-next/→packages/。-nextと"private": trueを外してmajorとしてpublishする。
完了条件:
packages/がnext系となり、現行テスト相当がすべて通る。@vivliostyle/vfmと各サブパッケージがmajor更新としてpublishされる。
現状(Phase 0調査)
2026-10時点の main を対象に調査した。
ツールチェイン
- ツールチェインはESM化済み(
"type": "module"、tsc直出力、vitest 4)。CJS固有のイディオムは残っていない。 - 旧世代なのは依存セットとそれに合わせた書き方のみ: unified 9、remark-parse 8、remark-rehype 8、mdast-util-to-hast 10と11の二重依存、vfile 4、
@types/{unist,mdast,hast}2/3/2。 - 全パッケージに
exportsフィールドが無い。READMEに載せているdeep import (@vivliostyle/vfm/lib/revive-parse、@vivliostyle/vfm/lib/revive-rehype)はこれに依存している。 - この文書を作るまで移行専用のドキュメントは無かった。ソース中の
@todo/TODOコメントが事実上の移行ノートだった:packages/vfm/src/plugins/code.ts–mdast-util-to-hast@>=13に上げたらhastフィールドを削るpackages/vfm/src/plugins/replace.ts–hastscriptが型を公開したらinterfaceの固定をやめるpackages/vfm/src/plugins/figure.ts–Image.altの再パースはremark-parse 8の挙動に依存packages/remark-ruby/src/ruby.ts–mdast-util-to-hast@>=13に上げたらhNameを削るpackages/remark-sectionize/src/section.ts–mdast-util-to-hast@>=13に上げたらhastフィールドを削る。@subtitleの扱い
移行先バージョン
2026-10-17時点の最新(2026-09調査時から変化なし)。
| パッケージ | 現行 | 移行先 |
|---|---|---|
| unified | 9.2 | 11.0.5 |
| remark-parse | 8.0 | 11.0.0 |
| remark-rehype | 8.1 | 11.1.2 |
| remark-gfm | – | 4.0.1 |
| mdast-util-to-hast | 10 / 11.3 | 13.2.1 |
| rehype-raw | 5.1 | 7.0.0 |
| rehype-stringify | 8.0 | 10.0.1 |
| rehype-format | 3.1 | 5.0.1 |
| vfile | 4.0 | 6.0.3 |
| to-vfile | 6.1 | 8.0.0 |
| hastscript | 7.2 | 9.0.1 |
| refractor | 3.6 | 5.0.0 |
| unist-util-visit | 4.1 | 5.1.0 |
| micromark | – | 4.0.3 |
| mdast-util-from-markdown | – | 2.1.0 |
| @types/mdast | 3 | 4.0.4 |
| @types/hast | 2 | 3.0.5 |
| @types/unist | 2 | 3.0.3 |
packages/vfm の実装分類(#277)
remarkパイプラインへの関与の仕方で分類した。各ファイルのremark 8依存箇所と影響するテストまで含めたモジュール単位のインベントリはremark13-vfm-inventory.mdにある。
| 分類 | 件数 | 対象 |
|---|---|---|
| remark-parse旧tokenizer | 1 | math |
| mdast transformer | 6 | slug, code, toc, figure, metadata, document |
| to-hast handler | 6 slot | math (inline / display), code, figure (paragraph経由), table, footnote 3種 |
| hast transformer | 6 | figure, replace, document, math, format, rewrite-extension |
| ラッパ/スキーマのみ | 5 | attr, line-breaks, options, table, footnotes |
math.tsはtokenizer / handler / hast transformerの3役を兼ねる。figure.tsはmdast transformer / handler / hast transformerの3役を兼ねる。document.tsはmdastをexportしているが、hast段で動く。
プロセッサ構成
- メイン プロセッサ(
packages/vfm/src/index.ts,VFM()):remarkParse→ mdast 11 slot (revive-parse.ts) → handlers付きremarkRehype→ hast 8 slot (revive-rehype.ts) →rehypeStringify。 - 2本目(
packages/vfm/src/plugins/metadata.ts,readMetadata()): footnotes, attr, frontmatterを使う独立したunifiedプロセッサ。 editPluginsフックが3配列(mdastPlugins,mdastToHastHandlers,hastPlugins)を公開APIとして露出する。各slotにはbrand<T>()のブランド型が付く。
mdast slotの順序: parseImageAltAsInline, lineBreaks, math, ruby, footnote, attr, slug, section, code, toc, frontmatter。
hast slotの順序: raw, deriveImgAltFromFigcaption, footnote, replace, rewriteRelativeHrefExtensions, document, math, format。
hast段の順序制約
deriveImgAltFromFigcaptionはrehype-rawの後に動く必要がある(展開後の<figcaption>を読む)。math(MathJax script注入)はdocumentの後に動く必要がある(<head>に書く)。
サブパッケージと外部プラグイン(#278)
各footnoteパッケージが依存する上流の出力まで含めたパッケージ単位の調査はremark13-subpackages.mdにある。
サブパッケージ
| パッケージ | 関与 | 影響 |
|---|---|---|
| remark-ruby | 旧tokenizer + handler | 大(再実装) |
| remark-footnote-dpub / gcpm | handler + hast | 中 |
| remark-footnote-pandoc | hastのみ | 中(前提となるendnote出力構造が変わる) |
| remark-sectionize | mdast transformer | 小(型のみ) |
| mdast-to-hast-table-cell | handler | 中(deep importあり) |
| rehype-rewrite-extension | hastのみ | 小 |
| vfm-internal-utils | hastscriptのみ | 小 |
remark-ruby は remark-parse の型を devDependencies からしか参照しておらず、公開している .d.ts がdevDependencyに依存している。
外部プラグイン
| プラグイン | 現行 | 状況 |
|---|---|---|
| remark-attr | 0.11 | 更新停止。自作が必要(#46, #211)。先行試作: origin/remark-attribute ブランチ(remark-parse 11向け属性拡張) |
| remark-shortcodes | 0.3 | 更新停止。存廃は#207で判断 |
| remark-footnotes | 2 | deprecated。remark-gfmに統合されたがinline note ^[...] は非対応 |
| remark-breaks | 1 | 4系で対応済み |
| remark-frontmatter | 2 | 5系で対応済み |
| remark-math | – | 6系が利用可能(#224の候補) |
主要な破壊点(#279)
remark 13へ移行すると必ず壊れる箇所。各PhaseのIssueはこの一覧を参照する。各項目の詳細(場所、原因、remark 13での対応物、修正、Phase、検証方法)と、Phase 0-1 / 0-2で追加で見つかった9件はremark13-breaking-points.mdにある。
- 旧tokenizer拡張:
this.Parser.prototype.inlineTokenizers/inlineMethodsへの追加(packages/vfm/src/plugins/math.ts,packages/remark-ruby/src/ruby.ts)。remark 13では無言で無効になる。micromark extensionへ書き直す。 - to-hast handlerの署名:
(h, node)とall(h, node)/one(h, ...)が(state, node, parent)とstate.all()/state.one()に変わる。全handlerとbuildFigure/buildDisplayMath/withTableCellTransform/ footnote 3パッケージが対象。 - unifiedのimport形式:
import unified from 'unified'とunified.Plugin/unified.Pluggableなどの名前空間型が使えない。utils.tsのbrand/mergePlugins/partialもこれに乗っている。 - remark-parseのオプション:
{ gfm: true, commonmark: true }は廃止。GFMはremark-gfmで有効化する。 - deep import:
mdast-util-to-hast/lib/handlers/table.js(packages/vfm/src/revive-rehype.ts,packages/mdast-to-hast-table-cell/tests)は13のexportsで閉じられる。 - altの再パース:
packages/vfm/src/plugins/figure.tsのthis.parse(image.alt)はremark-parse 8固有の挙動に依存(同ファイルのTODOコメント参照)。 - 旧Parser内部のテスト:
packages/vfm/tests/defs.test.ts(6件)はvfm.Parser.prototype.inlineMethodsなどを検証しており成立しない。 @types/mdast4の型名:StaticPhrasingContentMap→PhrasingContentMap、Content/HTMLの廃止など。module augmentationはpackages/vfm/src/plugins/{code,math,toc}.ts、packages/vfm/types/remark.d.ts、packages/remark-ruby/src/ruby.ts、packages/remark-sectionize/src/section.ts、packages/mdast-to-hast-table-cell/tests/rehype-format.d.tsに分散している。- MDAST期待値:テストは
unist-util-inspectのダンプ文字列を比較しており、ノード構造の変化で大半が書き直しになる。