remark 13 Migration: Breaking Points
Places that are guaranteed to break when VFM moves to remark 13 (Phase 0-3, #279). Each entry names the affected code, why it breaks, the remark 13 counterpart, the fix, the phase that owns it, and how to verify. The first nine entries are the list from #279; the rest were found while writing the packages/vfm inventory and the sub-package survey. Upstream behavior was checked against the packages in the 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) on 2026-10-17.
Phases refer to the sub-issues of #275: Phase 2 #281 (base libraries), Phase 3 #285 (syntax plugins on micromark), Phase 4 #293 (verification and tests).
Summary
| # | Breaking point | Kind | Phase |
|---|---|---|---|
| 1 | Legacy tokenizer extensions | Silent no-op | 3 |
| 2 | to-hast handler signature | Runtime error | 2 |
| 3 | unified import style | Compile error | 2 |
| 4 | remark-parse options | Silent no-op | 2 |
| 5 | Deep imports | Resolution error | 2 |
| 6 | Re-parsing Image.alt |
Wrong output | 3 |
| 7 | Tests of parser internals | Test failure | 4 |
| 8 | @types/mdast 4 type names |
Compile error | 2 |
| 9 | MDAST expectations in tests | Test failure | 4 |
| 10 | hastscript 9 child / properties detection | Wrong output | 2 |
| 11 | footnoteById is a Map |
Runtime error | 2 |
| 12 | mdast-util-to-hast 13 endnote footer |
Wrong output | 2 |
| 13 | refractor 5 returns a Root |
Wrong output | 2 |
| 14 | hast-util-raw 9 signature |
Compile error | 2 |
| 15 | Inline footnote node disappears | Silent no-op | 3 |
| 16 | findAndReplace fallback in math.ts |
Wrong output | 3 |
| 17 | Legacy external plugins | Silent no-op | 3 |
| 18 | Sub-package test utilities | Test failure | 4 |
| 19 | Type resolution across the two generations in one workspace | Compile error | 1 / 2 |
"Silent no-op" entries are the dangerous ones: the build and the processor run, and only the HTML output shows that a syntax was not parsed.
From #279
1. Legacy tokenizer extensions
- Where
packages/vfm/src/plugins/math.ts(mdast)packages/remark-ruby/src/ruby.ts(mdast)
- Why
- Both attach tokenizers to
this.Parser.prototype.inlineTokenizers/inlineMethods. remark-parse 10+ setsthis.parser(lowercase) to amdast-util-from-markdownwrapper and unified 11 no longer hasParser, sothis.Parserisundefined. Both plugins guard on it (if (!this.Parser) return) and therefore do nothing. The$...$and{base|ruby}syntaxes come out as plain text.
- Both attach tokenizers to
- Counterpart
- micromark syntax extensions registered through
this.data('micromarkExtensions') mdast-util-from-markdownextensions registered throughthis.data('fromMarkdownExtensions')- remark-parse 11 reads both lists.
- micromark syntax extensions registered through
- Fix
- Rewrite both as micromark + from-markdown extensions.
- For math, remark-math 6 is the candidate (#224); its node names (
inlineMath/math) and field (value) differ from VFM's (inlineMath/displayMath,data.value), so either the handlers change or a VFM extension keeps the old shape. - Ruby needs an inline extension whose base text is tokenized by micromark so that nested inline syntax keeps working.
- Verify
tests/math.test.tstests/math-mathml.test.tspackages/remark-ruby/tests/ruby.test.ts- Add a test that fails if the syntax is silently unparsed (for example, assert that no literal
$survives in the output of a math test).
2. to-hast handler signature
- Where
math.ts(handlerInlineMath,handlerDisplayMath)math.ts(buildDisplayMath, takes a node only)code.ts(handler)revive-rehype.ts(paragraph)figure.ts(buildFigure)remark-ruby(handler)mdast-to-hast-table-cell(withTableCellTransform,TableCellHook)remark-footnote-dpub/gcpm(three handlers each)
- Why
mdast-util-to-hast13 calls handlers as(state, node, parent).h(node, tagName, props, children)no longer exists;allandoneare not exported.
- Counterpart
state.all(node)state.one(node, parent)state.patch(node, element)(copies position)state.applyData(node, element)(applieshName/hProperties/hChildren)- Elements are built as plain objects or with hastscript.
- Fix
- Convert each handler. The public
TableCellHooktype ofmdast-to-hast-table-cell, which receives{ h }, becomes{ state }or a narrowed subset.
- Convert each handler. The public
- Verify
- HTML expectations of every handler test
tests/edit-plugins.test.tsfor handler replacement througheditPlugins
3. unified import style
- Where
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}- every test utility
- Why
- unified 10+ exports
{ unified }and named types (Plugin,Pluggable,PluggableList,Processor,Transformer).import unified from 'unified'andunified.Pluginfail to compile.
- unified 10+ exports
- Counterpart
import { unified, type Plugin, type Pluggable } from 'unified'.Pluginis generic over parameters and tree types.
- Fix
- Mechanical replacement.
brand<T>(),mergePlugins, andpartialinutils.tskeep their shape with the named types. Theunified.PluggableList<unified.Settings>cast inmetadata.tsis dropped.
- Mechanical replacement.
- Verify
tscacross the workspace
4. remark-parse options
- Where
packages/vfm/src/index.ts(VFM())packages/vfm/src/plugins/metadata.ts(parseMarkdown)- every sub-package test utility
- All pass
[remarkParse, { gfm: true, commonmark: true }].
- Why
- remark-parse 11 forwards its options to
mdast-util-from-markdown, which has nogfmorcommonmarkoption. CommonMark is the only mode. The call type-checks only against the old types and does nothing at runtime, so GFM tables, strikethrough, autolink literals, and footnote references are not parsed until remark-gfm is added.
- remark-parse 11 forwards its options to
- Counterpart
remark-gfm4 as an mdast slot, before any plugin that reads GFM nodes
- Fix
- Replace the options with
remarkGfmin the slot list..data('settings', { position })is also forwarded tofromMarkdownand ignored; positions are always present.
- Replace the options with
- Verify
tests/table.test.tstests/footnotes.test.ts- the MDAST dumps of any test with GFM syntax
5. Deep imports
- Where
packages/vfm/src/revive-rehype.tspackages/mdast-to-hast-table-cell/tests/utils.tspackages/mdast-to-hast-table-cell/tests/composition.test.ts- All import
mdast-util-to-hast/lib/handlers/table.js.
- Why
mdast-util-to-hast13 has"exports": "./index.js"; anylib/path fails to resolve.
- Counterpart
import { defaultHandlers } from 'mdast-util-to-hast'anddefaultHandlers.table
- Fix
- Replace the import. Also decide whether VFM's own packages add an
exportsfield; the README's@vivliostyle/vfm/lib/revive-parsedeep import depends on there being none.
- Replace the import. Also decide whether VFM's own packages add an
- Verify
- Build
packages/mdast-to-hast-table-cell/tests
6. Re-parsing Image.alt
- Where
packages/vfm/src/plugins/figure.ts(parseImageAltAsInline):this.parse(image.alt)
- Why
- remark-parse 8 stored the raw source of the alt text, so
kept the asterisks inaltand the plugin could re-parse them. micromark decodesaltto plain text (bold caption) before any plugin runs, so there is nothing left to re-parse.this.parseitself still exists on the unified processor.
- remark-parse 8 stored the raw source of the alt text, so
- Counterpart
- The raw caption is only available during tokenization. A from-markdown extension can record the source slice of the image label (for example as
data.rawAlt) or keep the label's child tokens.
- The raw caption is only available during tokenization. A from-markdown extension can record the source slice of the image label (for example as
- Fix
- Replace the re-parse with a VFM extension that keeps the inline children of the image label, and have
buildFigureread them. The non-standardImage.childrenconvention should become a typed field.
- Replace the re-parse with a VFM extension that keeps the inline children of the image label, and have
- Verify
tests/figure.test.ts, in particular theparseFigcaptionAsInlinecases and alt derivation (deriveImgAltFromFigcaption)
7. Tests of parser internals
- Where
packages/vfm/tests/defs.test.ts(6 tests), asserting:vfm.Parser.prototype.inlineMethodsblockMethodsinterruptParagraphinterruptListinterruptBlockquoteinterruptFootnoteDefinition
- Why
- None of these exist in remark-parse 11.
- Counterpart
- The lists
this.data('micromarkExtensions')andthis.data('fromMarkdownExtensions')on a frozen processor
- The lists
- Fix
- Replace with tests that assert the registered extensions (count or identity), or delete the file and rely on behavior tests.
- Verify
- The replacement tests themselves
8. @types/mdast 4 type names
- Where
packages/vfm/src/plugins/math.ts(StaticPhrasingContentMap)packages/vfm/src/plugins/toc.ts(Content,BlockContentMap)packages/vfm/src/plugins/code.ts(unistDataaugmentation)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
- Why
@types/mdast4 renamesStaticPhrasingContentMaptoPhrasingContentMap,ContenttoRootContent,HTMLtoHtml, and drops theContentunion.@types/unist3Datais augmented bymdast-util-to-hast13 itself (hName,hProperties,hChildren), so the local augmentations duplicate it.
- Counterpart
PhrasingContentMapBlockContentMap(unchanged)RootContentHtmlimport 'mdast-util-to-hast'for theDatafields
- Fix
- Rename, remove the duplicated
Dataaugmentations (keepfigcaptionTitleincode.tsandrubyTextin ruby), and deleterehype-format.d.tsoncerehype-format5 ships types.
- Rename, remove the duplicated
- Verify
tsc
9. MDAST expectations in tests
- Where
- Every
packages/vfm/tests/*.test.tsthat usesbuildProcessorTestingCode(tests/utils.ts). The MDAST is compared as aunist-util-inspectdump with positions anddata:lines stripped.
- Every
- Why
- Node shapes change with the new syntaxes, and
unist-util-inspect8 may also format differently. The affected nodes:inlineMath/mathfrom remark-math- remark-gfm footnote nodes
- attribute carrier nodes from the attr rewrite
- ruby and inline note nodes
- Node shapes change with the new syntaxes, and
- Fix
- Regenerate the expected dumps after each syntax lands and review the diff by hand; keep the HTML expectation as the behavioral check.
- Verify
- The tests themselves. Expect the largest churn in:
figure.test.tsmath.test.tsfootnotes.test.tscode.test.ts
- The tests themselves. Expect the largest churn in:
Found in Phase 0-1 and 0-2
10. hastscript 9 child / properties detection
- Where
packages/vfm/src/plugins/document.ts:h('head', ...createHead())(theh('html', props, [u('text', '\n'), ...])call is fine)packages/remark-footnote-dpub/src/index.ts:h('sup', u('text', '1'))- any user-supplied
ElementFactorypassed tobuildElement
- Why
- hastscript 9 decides whether the second argument is properties with an
isChildcheck: an object is a child only if it has an object-valued field (other than an array of strings / numbers) or achildrenarray. A text node{ type: 'text', value: '\n' }has neither, so it is treated as properties and rendered astype="text" value="..."attributes with no text child.
- hastscript 9 decides whether the second argument is properties with an
- Counterpart
- Pass children as one array or after an explicit properties object:
h('sup', {}, u('text', '1')).
- Pass children as one array or after an explicit properties object:
- Fix
- Audit every
h()call whose second argument can be a text node. hastscript 7 accepted them.
- Audit every
- Verify
tests/index.test.ts(document wrapper,<head>contents)packages/remark-footnote-dpub/tests
11. footnoteById is a Map
- Where
packages/remark-footnote-dpub/src/index.tspackages/remark-footnote-gcpm/src/index.ts- Accesses:
identifier in ctx.footnoteById,ctx.footnoteById[id],ctx.footnoteById[identifier] = ...
- Why
mdast-util-to-hast13state.footnoteByIdis aMap<string, FootnoteDefinition>keyed byString(identifier).toUpperCase(). Theincheck and index access returnfalse/undefined, and assignment adds an own property thatstatenever reads.
- Counterpart
state.footnoteById.has(id),.get(id),.set(id, def)state.footnoteOrderandstate.footnoteCountstrack numbering and duplicates.
- Fix
- Convert the accesses. Consider using
footnoteOrder/footnoteCountsinstead of the packages' own counters.
- Convert the accesses. Consider using
- Verify
packages/remark-footnote-{dpub,gcpm}/teststests/footnotes.test.ts
12. mdast-util-to-hast 13 endnote footer
- Where
packages/remark-footnote-pandoc/src/index.ts, selectors:div.footnotesli[id^="fn-"]sup[id^="fnref-"]:has(a:only-child[href^="#fn-"].footnote-ref)a.footnote-backref
- Why
- None of the current selectors match the v13 footer, so the transformer leaves the default footer untouched. The v13 footer:
- Area:
<section data-footnotes class="footnotes">with an<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:
- None of the current selectors match the v13 footer, so the transformer leaves the default footer untouched. The v13 footer:
- Counterpart
remark-rehype11 options:clobberPrefix,footnoteLabel,footnoteLabelTagName,footnoteLabelProperties,footnoteBackLabel,footnoteBackContent- Custom
footnoteReference/footnoteDefinitionhandlers plus a footer built fromstate.footnoteOrder
- Fix
- Either rewrite the selectors against the v13 footer, or emit the Pandoc structure directly from handlers (preferred; see the sub-package survey).
- Verify
packages/remark-footnote-pandoc/teststests/footnotes.test.ts
13. refractor 5 returns a Root
- Where
packages/vfm/src/plugins/code.ts(mdast):node.data.hChildren = refractor.highlight(value, lang)
- Why
- refractor 3 returned an array of hast nodes. refractor 4+ returns
{ type: 'root', children }. Assigning the root tohChildrennests arootinside<code>, whichrehype-stringifyrenders as its children in practice but which breakshChildrentyping and any hast consumer that expects element content.
- refractor 3 returned an array of hast nodes. refractor 4+ returns
- Counterpart
refractor.highlight(value, lang).children
- Fix
- Take
.children. refractor 5 also drops the default export in favor ofimport { refractor } from 'refractor', and language registration moves torefractor/<lang>paths.
- Take
- Verify
tests/code.test.tshighlighting cases
14. hast-util-raw 9 signature
- Where
packages/vfm/src/plugins/figure.ts(parseHtml):raw(u('root', [u('raw', value)]))
- Why
hast-util-raw9 israw(tree, options)with a named export and returnsNodes; the default export is gone, and therawnode type must be declared throughmdast-util-to-hast's augmentation.
- Counterpart
import { raw } from 'hast-util-raw';raw(tree)still accepts a root with arawchild.
- Fix
- Update the import and the return type cast.
- Verify
tests/figure.test.tscases with HTML comments inside the image paragraph
15. Inline footnote node disappears
- Where
packages/vfm/src/plugins/slug.ts(child.type !== 'footnote'filter)packages/vfm/src/plugins/metadata.ts(child.type !== 'footnote'filter)packages/vfm/src/plugins/footnotes.ts(inlineNotes: true)- the
footnotehandlers ofremark-footnote-dpub/gcpm tests/footnotes.test.ts
- Why
remark-footnotes2 produced afootnotenode for^[text]. remark-gfm 4 has no inline notes, so the node type never appears and^[text]is rendered as literal text. The filters and handlers become dead code without any error.
- Counterpart
- None upstream. A VFM micromark extension must define the syntax and the node.
- Fix
- Write the inline-note extension first (it is the shared dependency of slug, metadata, and the footnote packages) and update the node type name if it changes.
- Verify
tests/footnotes.test.tsinline casestests/metadata.test.tstitle extraction with footnotes
16. findAndReplace fallback in math.ts
- Where
packages/vfm/src/plugins/math.ts(mdast), the branch taken whenthis.Parseris absent
- Why
- The fallback was written for "remark 13 or later" but runs after parsing, on
textnodes.$**x**$is alreadytext('$'), strong, text('$'), so the regex never sees the whole formula, and$inside code spans or links is matched where the tokenizer excluded it (notInLink). In remark 13 this branch is the one that runs (see #1), so math output is wrong rather than missing.
- The fallback was written for "remark 13 or later" but runs after parsing, on
- Fix
- Delete the fallback together with the tokenizer and move to a micromark extension.
- Verify
tests/math.test.tscases with inline markup inside formulas and$inside code
17. Legacy external plugins
- Where
remark-attr0.11 (attr.ts,remark-sectionizetests)remark-shortcodes0.3 (toc.ts)remark-footnotes2 (footnotes.ts, footnote package tests)remark-breaks1 (line-breaks.ts,remark-rubytests)
- Why
- All four patch
this.Parser.prototype. Withthis.Parserundefined they return early, so attributes,[[toc]], footnotes, and hard breaks stop working without an error.code.tsalso carries a workaround for remark-attr parsing code content as attributes whenmetais empty; it becomes dead code.
- All four patch
- Counterpart
remark-breaks4 (transformer, drop-in)remark-gfm4 (footnote references and definitions)- VFM extensions for attributes and inline notes
remark-directive4 or a block extension for[[toc]]if kept (#207)
- Fix
- Per plugin, see the sub-package survey. Remove the remark-attr workaround from
code.ts.
- Per plugin, see the sub-package survey. Remove the remark-attr workaround from
- Verify
tests/attr.test.tstests/code.test.tstests/line-breaks.test.tstests/metadata.test.ts([[toc]]detection)packages/remark-sectionize/tests({hidden})
18. Sub-package test utilities
- Where
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
- Why
- Each builds its own processor with
import unified from 'unified',remark-parse8 options, andremark-footnotes/remark-attr/remark-breaks1 fromdevDependencies. They hit #1, #3, #4, #5, and #17 at once.
- Each builds its own processor with
- Fix
- Port each utility together with its package, using:
{ unified }- remark-gfm
- remark-breaks 4
- the VFM inline-note and attribute extensions once they exist
defaultHandlers.table
- Port each utility together with its package, using:
- Verify
pnpm testper package
19. Type resolution across the two generations in one workspace
- Where
pnpm-workspace.yaml(overrides,packageExtensions)@types/mdast@3/@types/mdast@4/@types/hast@2/@types/hast@3, which declare@types/unist: "*"- remark 8 generation packages whose
.d.tsimportunist,unified,vfile,hastscriptwithout declaring the dependency: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@3 - remark 13 generation packages with the same gap for
vfile:remark-parse@11,remark-stringify@11,rehype-stringify@10
- Why
- Found in Phase 2. With
packages/on unist 2 andpackages-next/on unist 3 in one pnpm workspace, every@types/unist: "*"range resolves to one version, and every undeclared type import resolves through pnpm's single hoisted copy innode_modules/.pnpm/node_modules. Whichever generation loses gets types from the other major:Parentscollapses tonever,PluginandProcessorcome from the wrong unified, and the build of the losing tree fails although its ownpackage.jsonis correct.
- Found in Phase 2. With
- Counterpart
- pnpm
overrideswith a parent selector ('@types/mdast@4>@types/unist': ^3.0.0) pin the*child per parent major. - pnpm
packageExtensionsadd the missingdependenciesto the published packages so they resolve their own copy instead of the hoisted one.
- pnpm
- Fix
- Both tables live in
pnpm-workspace.yamlwith a comment. They are scaffolding for the co-existence period and are removed in Phase 5 (#296) together withpackages/.
- Both tables live in
- Verify
pnpm install --frozen-lockfile && pnpm build && pnpm testat the root, which runs both trees.- If a new generation-specific dependency is added, check
node_modules/.pnpm/<pkg>/node_modules/@types/unist/package.jsonfor the version it resolved.
Dependencies between fixes
- #15 (inline note node) and #17 (attribute extension) are inputs to #1, #6, #9, #11, #12, and #18. Define those two node shapes before porting handlers or tests.
- #2 and #11 are done together per footnote package.
- #4 (remark-gfm) must land before any footnote or table test can pass.
- #10, #13, and #14 are independent library adaptations and can be done first in Phase 2.
- #19 is a workspace concern: it has to be in place before any
packages-next/dependency moves to the new majors, and it goes away withpackages/in Phase 5.