remark 13移行:破壊点
VFMをremark 13へ移行すると必ず壊れる箇所(Phase 0-3, #279)。各項目に、該当コード、壊れる理由、remark 13での対応物、修正、担当Phase、検証方法を記す。最初の9件は#279の一覧で、残りはpackages/vfm インベントリとサブパッケージ調査を書く中で見つけたもの。上流の挙動は2026-10-17にpnpm storeのパッケージ(unified 11.0.5, remark-parse 11.0.0, mdast-util-to-hast 13.2.1, hastscript 9.0.1, hast-util-raw 9.1.0, refractor 5.0.0)で確認した。
Phaseは#275のsub-issueを指す: Phase 2 #281 (基盤ライブラリ)、Phase 3 #285 (構文プラグインのmicromark化)、Phase 4 #293 (検証とテスト)。
一覧
| # | 破壊点 | 種類 | Phase |
|---|---|---|---|
| 1 | 旧tokenizer拡張 | 無言で無効 | 3 |
| 2 | to-hast handlerの署名 | 実行時エラー | 2 |
| 3 | unifiedのimport形式 | コンパイル エラー | 2 |
| 4 | remark-parseのオプション | 無言で無効 | 2 |
| 5 | deep import | 解決エラー | 2 |
| 6 | Image.alt の再パース |
出力不正 | 3 |
| 7 | 旧Parser内部のテスト | テスト失敗 | 4 |
| 8 | @types/mdast 4の型名 |
コンパイル エラー | 2 |
| 9 | テストのMDAST期待値 | テスト失敗 | 4 |
| 10 | hastscript 9のchild / properties判定 | 出力不正 | 2 |
| 11 | footnoteById が Map |
実行時エラー | 2 |
| 12 | mdast-util-to-hast 13のendnote footer |
出力不正 | 2 |
| 13 | refractor 5が Root を返す |
出力不正 | 2 |
| 14 | hast-util-raw 9の署名 |
コンパイル エラー | 2 |
| 15 | inline footnoteノードの消滅 | 無言で無効 | 3 |
| 16 | math.ts の findAndReplace フォールバック |
出力不正 | 3 |
| 17 | 旧方式の外部プラグイン | 無言で無効 | 3 |
| 18 | サブパッケージのテスト ユーティリティ | テスト失敗 | 4 |
| 19 | 1つのworkspaceに2世代が併存することによる型解決 | コンパイル エラー | 1 / 2 |
「無言で無効」の項目が危険。ビルドもプロセッサも動き、HTML出力を見るまで構文がパースされていないことに気付けない。
#279の項目
1.旧tokenizer拡張
- 場所
packages/vfm/src/plugins/math.ts(mdast)packages/remark-ruby/src/ruby.ts(mdast)
- 理由
- 両者ともtokenizerを
this.Parser.prototype.inlineTokenizers/inlineMethodsに付ける。remark-parse 10以降はthis.parser(小文字)にmdast-util-from-markdownのラッパーを設定し、unified 11にはParserが無いため、this.Parserはundefined。両プラグインはこれをガードにしており(if (!this.Parser) return)、何もしない。$...$と{base|ruby}の構文はプレーンテキストとして出る。
- 両者ともtokenizerを
- 対応物
this.data('micromarkExtensions')で登録するmicromark構文拡張this.data('fromMarkdownExtensions')で登録するmdast-util-from-markdown拡張- remark-parse 11は両リストを読む。
- 修正
- 両者をmicromark + from-markdown拡張として書き直す。
- mathはremark-math 6が候補(#224)。ノード名(
inlineMath/math)とフィールド(value)がVFM (inlineMath/displayMath,data.value)と異なるため、handlerを変えるかVFM拡張で旧形状を保つ。 - rubyはベース テキストをmicromarkにトークン化させるインライン拡張が必要で、入れ子のインライン記法を維持する。
- 検証
tests/math.test.tstests/math-mathml.test.tspackages/remark-ruby/tests/ruby.test.ts- 構文が無言で未パースだと失敗するテストを足す(例: mathテストの出力にリテラルの
$が残らないことを確認する)。
2. to-hast handlerの署名
- 場所
math.ts(handlerInlineMath,handlerDisplayMath)math.ts(buildDisplayMath、ノードのみ受け取る)code.ts(handler)revive-rehype.ts(paragraph)figure.ts(buildFigure)remark-ruby(handler)mdast-to-hast-table-cell(withTableCellTransform,TableCellHook)remark-footnote-dpub/gcpm(各3 handler)
- 理由
mdast-util-to-hast13はhandlerを(state, node, parent)で呼ぶ。h(node, tagName, props, children)は無くなり、allとoneはexportされない。
- 対応物
state.all(node)state.one(node, parent)state.patch(node, element)(positionをコピー)state.applyData(node, element)(hName/hProperties/hChildrenを適用)- 要素はplain objectかhastscriptで組む。
- 修正
- 各handlerを変換する。
{ h }を受け取るmdast-to-hast-table-cellの公開型TableCellHookは{ state }か絞った部分集合になる。
- 各handlerを変換する。
- 検証
- 全handlerテストのHTML期待値
editPluginsによるhandler置き換えはtests/edit-plugins.test.ts
3. unifiedのimport形式
- 場所
packages/vfm/src/index.tspackages/vfm/src/utils.tspackages/vfm/src/revive-parse.tspackages/vfm/src/revive-rehype.tspackages/vfm/src/plugins/metadata.tspackages/vfm/src/plugins/figure.tspackages/vfm/src/plugins/footnotes.tspackages/vfm/src/plugins/math.tsremark-footnote-{dpub,gcpm,pandoc}- すべてのテスト ユーティリティ
- 理由
- unified 10以降は
{ unified }と名前付き型(Plugin,Pluggable,PluggableList,Processor,Transformer)をexportする。import unified from 'unified'とunified.Pluginはコンパイルできない。
- unified 10以降は
- 対応物
import { unified, type Plugin, type Pluggable } from 'unified'。Pluginはパラメーターとツリー型のジェネリック。
- 修正
- 機械的な置き換え。
utils.tsのbrand<T>()、mergePlugins、partialは名前付き型でそのままの形を保てる。metadata.tsのunified.PluggableList<unified.Settings>キャストは削除する。
- 機械的な置き換え。
- 検証
- workspace全体の
tsc
- workspace全体の
4. remark-parseのオプション
- 場所
packages/vfm/src/index.ts(VFM())packages/vfm/src/plugins/metadata.ts(parseMarkdown)- すべてのサブパッケージ テスト ユーティリティ
- いずれも
[remarkParse, { gfm: true, commonmark: true }]を渡している。
- 理由
- remark-parse 11はオプションを
mdast-util-from-markdownに転送するが、そこにgfmやcommonmarkは無い。モードはCommonMarkのみ。この呼び出しは旧型でしか型検査を通らず、実行時には何もしないため、remark-gfmを足すまでGFMのtable、取り消し線、autolinkリテラル、footnote参照はパースされない。
- remark-parse 11はオプションを
- 対応物
- GFMノードを読むプラグインより前のmdast slotとしての
remark-gfm4
- GFMノードを読むプラグインより前のmdast slotとしての
- 修正
- オプションをslotリストの
remarkGfmに置き換える。.data('settings', { position })もfromMarkdownに転送されて無視される。positionは常に付く。
- オプションをslotリストの
- 検証
tests/table.test.tstests/footnotes.test.ts- GFM構文を含むテストのMDASTダンプ
5. deep import
- 場所
packages/vfm/src/revive-rehype.tspackages/mdast-to-hast-table-cell/tests/utils.tspackages/mdast-to-hast-table-cell/tests/composition.test.ts- いずれも
mdast-util-to-hast/lib/handlers/table.jsをimportしている。
- 理由
mdast-util-to-hast13は"exports": "./index.js"を持ち、lib/配下のパスは解決できない。
- 対応物
import { defaultHandlers } from 'mdast-util-to-hast'とdefaultHandlers.table
- 修正
- importを置き換える。あわせてVFM自身のパッケージに
exportsを付けるか決める。READMEの@vivliostyle/vfm/lib/revive-parsedeep importはexportsが無いことに依存している。
- importを置き換える。あわせてVFM自身のパッケージに
- 検証
- ビルド
packages/mdast-to-hast-table-cell/tests
6. Image.alt の再パース
- 場所
packages/vfm/src/plugins/figure.ts(parseImageAltAsInline):this.parse(image.alt)
- 理由
- remark-parse 8はaltテキストの生ソースを保持していたため、
のaltにアスタリスクが残り、プラグインがそれを再パースできた。micromarkはプラグインが動く前にaltをプレーンテキスト(bold caption)にdecodeするので、再パースする対象が残らない。this.parse自体はunifiedプロセッサに引き続き存在する。
- remark-parse 8はaltテキストの生ソースを保持していたため、
- 対応物
- 生のキャプションはトークン化中にしか得られない。from-markdown拡張で画像ラベルのソース スライスを記録する(例:
data.rawAlt)か、ラベルの子トークンを保持する。
- 生のキャプションはトークン化中にしか得られない。from-markdown拡張で画像ラベルのソース スライスを記録する(例:
- 修正
- 再パースを、画像ラベルのインライン子要素を保持するVFM拡張に置き換え、
buildFigureがそれを読むようにする。非標準のImage.childrenの慣習は型付きフィールドにする。
- 再パースを、画像ラベルのインライン子要素を保持するVFM拡張に置き換え、
- 検証
tests/figure.test.ts、特にparseFigcaptionAsInlineのケースとalt導出(deriveImgAltFromFigcaption)
7.旧Parser内部のテスト
- 場所
packages/vfm/tests/defs.test.ts(6件)。検証対象:vfm.Parser.prototype.inlineMethodsblockMethodsinterruptParagraphinterruptListinterruptBlockquoteinterruptFootnoteDefinition
- 理由
- remark-parse 11にはいずれも存在しない。
- 対応物
- freezeしたプロセッサの
this.data('micromarkExtensions')とthis.data('fromMarkdownExtensions')のリスト
- freezeしたプロセッサの
- 修正
- 登録された拡張(件数または同一性)を検証するテストに置き換えるか、ファイルを削除して挙動テストに任せる。
- 検証
- 置き換えたテスト自体
8. @types/mdast 4の型名
- 場所
packages/vfm/src/plugins/math.ts(StaticPhrasingContentMap)packages/vfm/src/plugins/toc.ts(Content,BlockContentMap)packages/vfm/src/plugins/code.ts(unistDataのaugmentation)packages/vfm/types/remark.d.tspackages/remark-ruby/src/ruby.ts(unistData)packages/remark-sectionize/src/section.ts(Content,HTML,BlockContentMap,unistData)packages/mdast-to-hast-table-cell/tests/rehype-format.d.ts
- 理由
@types/mdast4はStaticPhrasingContentMapをPhrasingContentMapに、ContentをRootContentに、HTMLをHtmlに改名し、Contentunionを廃止した。@types/unist3のDataはmdast-util-to-hast13自身がaugmentationする(hName,hProperties,hChildren)ため、ローカルのaugmentationは重複になる。
- 対応物
PhrasingContentMapBlockContentMap(変更なし)RootContentHtmlDataフィールドにはimport 'mdast-util-to-hast'
- 修正
- 改名し、重複した
Dataaugmentationを削除する(code.tsのfigcaptionTitleとrubyのrubyTextは残す)。rehype-format5が型を同梱したらrehype-format.d.tsを削除する。
- 改名し、重複した
- 検証
tsc
9.テストのMDAST期待値
- 場所
buildProcessorTestingCode(tests/utils.ts)を使うすべてのpackages/vfm/tests/*.test.ts。MDASTはpositionとdata:行を除いたunist-util-inspectのダンプとして比較される。
- 理由
- 新しい構文でノード形状が変わり、
unist-util-inspect8の書式も変わりうる。影響するノード:- remark-mathの
inlineMath/math - remark-gfmのfootnoteノード
- attr書き直しによる属性の運搬ノード
- rubyとinline noteのノード
- remark-mathの
- 新しい構文でノード形状が変わり、
- 修正
- 各構文が揃うたびに期待ダンプを再生成し、差分を手で確認する。挙動の検証はHTML期待値に任せる。
- 検証
- テスト自体。変更が最も大きい見込みのファイル:
figure.test.tsmath.test.tsfootnotes.test.tscode.test.ts
- テスト自体。変更が最も大きい見込みのファイル:
Phase 0-1 / 0-2で見つかった項目
10. hastscript 9のchild / properties判定
- 場所
packages/vfm/src/plugins/document.ts:h('head', ...createHead())(h('html', props, [u('text', '\n'), ...])は問題なし)packages/remark-footnote-dpub/src/index.ts:h('sup', u('text', '1'))buildElementに渡されるユーザー定義のElementFactory
- 理由
- hastscript 9は第2引数がpropertiesかどうかを
isChild判定で決める。オブジェクトがchildと見なされるのは、(文字列/数値の配列以外の)オブジェクト値のフィールドかchildren配列を持つ場合のみ。textノード{ type: 'text', value: '\n' }はどちらも持たないためpropertiesと扱われ、type="text" value="..."属性として描画され、テキスト子要素が無くなる。
- hastscript 9は第2引数がpropertiesかどうかを
- 対応物
- childrenを1つの配列で渡すか、明示的なpropertiesオブジェクトの後に渡す:
h('sup', {}, u('text', '1'))。
- childrenを1つの配列で渡すか、明示的なpropertiesオブジェクトの後に渡す:
- 修正
- 第2引数がtextノードになりうる
h()呼び出しをすべて監査する。hastscript 7はこれを受け付けていた。
- 第2引数がtextノードになりうる
- 検証
tests/index.test.ts(document wrapper、<head>の内容)packages/remark-footnote-dpub/tests
11. footnoteById が Map
- 場所
packages/remark-footnote-dpub/src/index.tspackages/remark-footnote-gcpm/src/index.ts- アクセス箇所:
identifier in ctx.footnoteById、ctx.footnoteById[id]、ctx.footnoteById[identifier] = ...
- 理由
mdast-util-to-hast13のstate.footnoteByIdはString(identifier).toUpperCase()をキーとするMap<string, FootnoteDefinition>。in判定とインデックス アクセスはfalse/undefinedを返し、代入はstateが決して読まないown propertyを追加する。
- 対応物
state.footnoteById.has(id)、.get(id)、.set(id, def)state.footnoteOrderとstate.footnoteCountsが採番と重複を追跡する。
- 修正
- アクセスを変換する。パッケージ独自のカウンターの代わりに
footnoteOrder/footnoteCountsを使うことを検討する。
- アクセスを変換する。パッケージ独自のカウンターの代わりに
- 検証
packages/remark-footnote-{dpub,gcpm}/teststests/footnotes.test.ts
12. mdast-util-to-hast 13のendnote footer
- 場所
packages/remark-footnote-pandoc/src/index.tsのセレクター:div.footnotesli[id^="fn-"]sup[id^="fnref-"]:has(a:only-child[href^="#fn-"].footnote-ref)a.footnote-backref
- 理由
- 現在のセレクターはどれもv13のfooterに一致せず、transformerは既定footerを触らずに残す。v13のfooter:
- Area:
<section data-footnotes class="footnotes">と<h2 id="footnote-label" class="sr-only"> - Element:
<li id="user-content-fn-id"> - Call:
<sup><a href="#user-content-fn-id" id="user-content-fnref-id" data-footnote-ref aria-describedby="footnote-label"> - Backlink:
<a href="#user-content-fnref-id" data-footnote-backref class="data-footnote-backref" aria-label="Back to reference N">
- Area:
- 現在のセレクターはどれもv13のfooterに一致せず、transformerは既定footerを触らずに残す。v13のfooter:
- 対応物
remark-rehype11のオプション:clobberPrefix、footnoteLabel、footnoteLabelTagName、footnoteLabelProperties、footnoteBackLabel、footnoteBackContent- カスタム
footnoteReference/footnoteDefinitionhandlerとstate.footnoteOrderから組むfooter
- 修正
- セレクターをv13 footerに合わせて書き直すか、handlerからPandoc構造を直接出力する(推奨。サブパッケージ調査を参照)。
- 検証
packages/remark-footnote-pandoc/teststests/footnotes.test.ts
13. refractor 5が Root を返す
- 場所
packages/vfm/src/plugins/code.ts(mdast):node.data.hChildren = refractor.highlight(value, lang)
- 理由
- refractor 3はhastノードの配列を返した。refractor 4以降は
{ type: 'root', children }を返す。rootをhChildrenに代入すると<code>の中にrootが入れ子になる。rehype-stringifyは実際にはそのchildrenを描画するが、hChildrenの型付けと、要素コンテンツを期待するhastコンシューマーは壊れる。
- refractor 3はhastノードの配列を返した。refractor 4以降は
- 対応物
refractor.highlight(value, lang).children
- 修正
.childrenを取る。refractor 5はdefault exportも廃止してimport { refractor } from 'refractor'になり、言語登録はrefractor/<lang>パスに移る。
- 検証
tests/code.test.tsのハイライト ケース
14. hast-util-raw 9の署名
- 場所
packages/vfm/src/plugins/figure.ts(parseHtml):raw(u('root', [u('raw', value)]))
- 理由
hast-util-raw9は名前付きexportのraw(tree, options)でNodesを返す。default exportは無くなり、rawノード型はmdast-util-to-hastのaugmentationで宣言する必要がある。
- 対応物
import { raw } from 'hast-util-raw'。raw(tree)はraw子要素を持つrootを引き続き受け付ける。
- 修正
- importと戻り値の型キャストを更新する。
- 検証
tests/figure.test.tsの画像段落内にHTMLコメントがあるケース
15. inline footnoteノードの消滅
- 場所
packages/vfm/src/plugins/slug.ts(child.type !== 'footnote'のフィルター)packages/vfm/src/plugins/metadata.ts(child.type !== 'footnote'のフィルター)packages/vfm/src/plugins/footnotes.ts(inlineNotes: true)remark-footnote-dpub/gcpmのfootnotehandlertests/footnotes.test.ts
- 理由
remark-footnotes2は^[text]に対してfootnoteノードを生成した。remark-gfm 4にinline noteは無いため、このノード型は決して現れず、^[text]はリテラルのテキストとして描画される。フィルターとhandlerはエラー無しにdead codeになる。
- 対応物
- 上流には無い。VFMのmicromark拡張で構文とノードを定義する必要がある。
- 修正
- inline note拡張を最初に書く(slug、metadata、footnoteパッケージの共通依存)。ノード型名が変わるなら更新する。
- 検証
tests/footnotes.test.tsのinlineケースtests/metadata.test.tsのfootnote付きタイトル抽出
16. math.ts の findAndReplace フォールバック
- 場所
packages/vfm/src/plugins/math.ts(mdast)、this.Parserが無いときに通る分岐
- 理由
- このフォールバックは「remark 13以降」向けに書かれたが、パース後に
textノード上で動く。$**x**$はすでにtext('$'), strong, text('$')になっているため正規表現は数式全体を見られず、tokenizerが除外していた(notInLink)コード スパンやリンク内の$に一致してしまう。remark 13ではこの分岐が実行される(#1参照)ので、mathの出力は欠落ではなく不正になる。
- このフォールバックは「remark 13以降」向けに書かれたが、パース後に
- 修正
- tokenizerとともにフォールバックを削除し、micromark拡張へ移る。
- 検証
tests/math.test.tsの数式内インライン記法のケースと、コード内の$のケース
17.旧方式の外部プラグイン
- 場所
remark-attr0.11 (attr.ts,remark-sectionizeテスト)remark-shortcodes0.3 (toc.ts)remark-footnotes2 (footnotes.ts, footnoteパッケージのテスト)remark-breaks1 (line-breaks.ts,remark-rubyテスト)
- 理由
- 4つとも
this.Parser.prototypeを書き換える。this.Parserがundefinedだと早期returnするため、属性、[[toc]]、footnote、hard breakがエラー無しに動かなくなる。code.tsにはmetaが空のときremark-attrがコード内容を属性としてパースする問題の回避策もあり、これはdead codeになる。
- 4つとも
- 対応物
remark-breaks4 (transformer、置き換えのみ)remark-gfm4 (footnoteの参照と定義)- 属性とinline noteのVFM拡張
[[toc]]を残すならremark-directive4かblock拡張(#207)
- 修正
- プラグインごとにサブパッケージ調査を参照。
code.tsのremark-attr回避策を削除する。
- プラグインごとにサブパッケージ調査を参照。
- 検証
tests/attr.test.tstests/code.test.tstests/line-breaks.test.tstests/metadata.test.ts([[toc]]検出)packages/remark-sectionize/tests({hidden})
18.サブパッケージのテスト ユーティリティ
- 場所
packages/remark-ruby/tests/ruby.test.tspackages/remark-footnote-{dpub,gcpm,pandoc}/tests/*.test.tspackages/remark-sectionize/tests/utils.tspackages/mdast-to-hast-table-cell/tests/utils.ts
- 理由
- それぞれ
import unified from 'unified'、remark-parse8オプション、devDependenciesのremark-footnotes/remark-attr/remark-breaks1で独自のプロセッサを組んでいる。#1、#3、#4、#5、#17に同時に当たる。
- それぞれ
- 修正
- 各ユーティリティをパッケージと一緒に移植する。使うもの:
{ unified }- remark-gfm
- remark-breaks 4
- できあがり次第VFMのinline noteと属性拡張
defaultHandlers.table
- 各ユーティリティをパッケージと一緒に移植する。使うもの:
- 検証
- パッケージごとの
pnpm test
- パッケージごとの
19. 1つのworkspaceに2世代が併存することによる型解決
- 場所
pnpm-workspace.yaml(overrides,packageExtensions)@types/unist: "*"を宣言している@types/mdast@3/@types/mdast@4/@types/hast@2/@types/hast@3.d.tsでunist、unified、vfile、hastscriptを依存宣言なしにimportしているremark 8世代のパッケージ:remark-parse@8、remark-rehype@8、remark-frontmatter@2、remark-footnotes@2、rehype-raw@5、rehype-stringify@8、unified@9、unist-builder@2、unist-util-is@4、vfile-location@3、hast-util-to-html@7、hast-util-from-parse5@6、hast-util-has-property@2、mdast-util-definitions@4、hast-util-to-string@2、@types/refractor@3vfileについて同じ欠落があるremark 13世代のパッケージ:remark-parse@11、remark-stringify@11、rehype-stringify@10
- 理由
- Phase 2で判明。1つのpnpm workspaceにunist 2の
packages/とunist 3のpackages-next/が併存すると、@types/unist: "*"はすべて1つのバージョンに解決され、依存宣言の無い型importはnode_modules/.pnpm/node_modulesにあるpnpmのhoist済みコピー1つに解決される。負けた世代は別majorの型を読むことになり、Parentsがneverに潰れ、PluginやProcessorが別のunifiedのものになり、自身のpackage.jsonが正しくてもそのツリーのビルドが失敗する。
- Phase 2で判明。1つのpnpm workspaceにunist 2の
- 対応物
- 親セレクター付きのpnpm
overrides('@types/mdast@4>@types/unist': ^3.0.0)で、*の子を親のmajorごとに固定する。 - pnpm
packageExtensionsで、公開パッケージに欠けているdependenciesを補い、hoist済みコピーではなく自身のコピーを解決させる。
- 親セレクター付きのpnpm
- 修正
- 両方の表は
pnpm-workspace.yamlにコメント付きで置いてある。併存期間のための足場であり、Phase 5 (#296)でpackages/とともに削除する。
- 両方の表は
- 検証
- ルートで
pnpm install --frozen-lockfile && pnpm build && pnpm testを実行する(両ツリーが対象)。 - 世代固有の依存を新たに追加したときは、
node_modules/.pnpm/<pkg>/node_modules/@types/unist/package.jsonで解決されたバージョンを確認する。
- ルートで
修正間の依存関係
- #15 (inline noteノード)と#17 (属性拡張)は#1、#6、#9、#11、#12、#18の入力になる。handlerやテストを移植する前に、この2つのノード形状を定義する。
- #2と#11はfootnoteパッケージごとに一緒に行う。
- #4 (remark-gfm)はfootnoteやtableのテストが通る前に入れる必要がある。
- #10、#13、#14は独立したライブラリ適応で、Phase 2の最初にできる。
- #19はworkspaceの問題で、
packages-next/の依存を新majorに上げる前に入れておく必要があり、Phase 5でpackages/とともに消える。