remark 13 Migration: Sub-packages and External Plugins
Survey of the sub-packages under packages/ and the external remark / rehype plugins VFM depends on, for the remark 13 migration (Phase 0-2, #278). It expands the summary in remark13-migration.md and complements the packages/vfm inventory. Surveyed against main as of 2026-10-17; upstream behavior was checked against the packages already present in the pnpm store (mdast-util-to-hast 13.2.1, hastscript 9.0.1, remark-rehype 11.1.2).
Change class follows the inventory: Rewrite (mechanism gone), Adapt (same mechanism, new API), Keep (type bumps only).
Sub-packages
| Package | Version | Stage | Impact | Change |
|---|---|---|---|---|
@vivliostyle/remark-ruby |
1.0.1 | legacy tokenizer + handler | Large | Rewrite |
@vivliostyle/remark-footnote-dpub |
1.0.1 | handler ×3 + hast | Medium | Adapt (handlers), Rewrite (inline note source) |
@vivliostyle/remark-footnote-gcpm |
1.0.1 | handler ×2 | Medium | Adapt (handlers), Rewrite (inline note source) |
@vivliostyle/remark-footnote-pandoc |
1.0.1 | hast only | Medium | Rewrite (selectors follow upstream output) |
@vivliostyle/remark-sectionize |
1.0.1 | mdast transformer | Small | Adapt (types, utility majors) |
@vivliostyle/mdast-to-hast-table-cell |
0.0.0 | handler wrapper | Medium | Adapt (handler signature, deep import) |
@vivliostyle/rehype-rewrite-extension |
0.0.0 | hast only | Small | Keep |
@vivliostyle/vfm-internal-utils |
1.0.1 | hastscript helper | Small | Keep |
Shared traits:
- No package has an
exportsfield. Every package publisheslib/withmain/typespointing at the compiled entry. - Every package that touches
mdast-util-to-hastdepends on 11.3 directly whileremark-rehype8 pulls 10.2. The handler signature andfootnoteByIdshape come from 11, the endnote footer output from 10. - Every test suite builds its own processor with
remark-parse8 options ({ gfm: true, commonmark: true }),remark-footnotes, orremark-attrfromdevDependencies. All test utilities need the same rewrite aspackages/vfm/src/index.ts. - The following are shared and move together:
hast-util-select5unist-builder3unist-util-visit4hastscript7@types/{hast,mdast,unist}2/3/2
remark-ruby
Source: packages/remark-ruby/src/ruby.ts.
- Parser
- An inline tokenizer for
{base|ruby}registered onthis.Parser.prototype.inlineTokenizers/inlineMethodsbeforetext. It callsthis.tokenizeInline(inlineContent, now)to parse the base text recursively, so ruby can contain emphasis, code, and other inline syntax. remark 13 ignores the registration silently.
- An inline tokenizer for
- Types
Eat,Parser, andTokenizerare imported fromremark-parse, which is only adevDependency, so the published.d.tscannot be consumed without it.- The local
Tokenizertype patches gaps in the remark-parse 8 typings:this.tokenizeInlineeat.now()- non-optional
Point.offset
- Augments
unistDatawithhName.
- Handler
(h, node)returnsh(node, 'ruby', [...all(h, node), rt]). Therttext is carried indata.rubyText.
- Change
- Rewrite the parser as a micromark extension plus an
mdast-util-from-markdownextension (enter/exithandlers that build arubynode withchildrenandrubyText). The nested inline parse is the hard part: the extension has to tokenize{…|as an inline container so that the base text is parsed by micromark, not re-parsed from a string. - Handler becomes
(state, node)withstate.all(node)andstate.patch/state.applyData. - Drop the
remark-parsetype import and theDataaugmentation.
- Rewrite the parser as a micromark extension plus an
- Tests
tests/ruby.test.tsbuildsremark-parse8 +remark-breaks1 +remark-rehype8 and registers the handler; expectations are HTML strings, so they can survive if the output is reproduced.
remark-footnote-dpub and remark-footnote-gcpm
Source: packages/remark-footnote-dpub/src/index.ts, packages/remark-footnote-gcpm/src/index.ts.
Both packages override the footnoteReference and footnote handlers (dpub also footnoteDefinition) and use @vivliostyle/vfm-internal-utils buildElement for the customizable elements.
- Handler state
- Handlers are
(ctx, node)and readctx.footnoteByIdas a plain object:identifier in ctx.footnoteByIdctx.footnoteById[id]- assignment for inline notes
- In
mdast-util-to-hast13state.footnoteByIdis aMapkeyed byString(identifier).toUpperCase()(same normalization as today), so every access becomeshas/get/set.all(ctx, node)becomesstate.all(node).
- Handlers are
- Inline notes
- The
footnotehandler consumes the inline note node (^[...]) thatremark-footnotesproduces and synthesizes afootnoteDefinitionon the fly. remark-gfm 4 has no inline notes, so this handler has no input until a VFM inline-note extension exists. The node type and shape are VFM's to define; the handlers should be written against that definition.
- The
- Numbering
- Both packages assign
refIndexat handler-invocation time and dpub renumbers in a final hast pass becausemdast-util-to-hast< 12.1.1 walked table cells in reverse (#129). With v13 the walk order is document order, so the renumber pass becomes an identity transform and can stay as a safety net or be removed. The default handler in v13 also tracks duplicates itself (state.footnoteCounts,-2suffix), which the custom handlers do not use.
- Both packages assign
- hastscript
- dpub builds
h('sup', u('text', '1')). hastscript 9 treats a plain text node passed in the properties position as properties (itsisChildcheck returns false for an object whose only values are strings), so the<sup>would gettype/valueattributes and no text. Pass children as an array or build the text node explicitly. Calls with an explicit properties object (h('a', {...}, child)) are unaffected.
- dpub builds
- dpub transformer
createReplaceDpubPlaceholdersis a hast transformer that replaces<div data-footnote-placeholder>with the queued<aside>and inserts inline-note asides after the nearest non-flow-container ancestor. It depends only on hast andhast-util-select, so it adapts with the utility majors.
- gcpm
hastTransformeris a no-op; all work is in the handlers.hastTransformer: unified.Pluginuses the namespace type.
- Change
- Adapt handlers to
(state, node)with theMapAPI. - Follow the inline note node definition.
- Fix the
h('sup', textNode)calls. - Replace
unified.Pluginwith the namedPlugintype.
- Adapt handlers to
- Tests
tests/dpub.test.tsandtests/gcpm.test.tsbuild processors withremark-footnotesand compare HTML. Inline-note cases need the new extension; the rest should hold.
remark-footnote-pandoc
Source: packages/remark-footnote-pandoc/src/index.ts.
-
Mechanism
- No handlers (
toHastHandlersare allundefined). Two hast transformers rewrite the endnote markup thatmdast-util-to-hast10 emits into a Pandoc-like<section role="doc-endnotes">, renumber calls by document order, and add backlinks for duplicate references.
- No handlers (
-
Coupling
-
Every selector is pinned to the v10 footer:
div.footnotesli[id^="fn-"]sup[id^="fnref-"]:has(a:only-child[href^="#fn-"].footnote-ref)a.footnote-backref
-
The v13 footer is different in every respect that the selectors touch:
mdast-util-to-hast10mdast-util-to-hast13Area <div class="footnotes"><section data-footnotes class="footnotes">with an<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">Duplicates Not handled -2,-3suffixes on call ids and extra backlinks -
remark-rehype11 exposes options that remove theuser-content-prefix and the label heading, and shape the backlink content:clobberPrefixfootnoteLabelfootnoteLabelTagNamefootnoteLabelPropertiesfootnoteBackLabelfootnoteBackContent
-
-
Change
- Rewrite the selectors and the call / backlink rewriting against the v13 footer, or (preferred) stop post-processing the default footer and emit the Pandoc structure from custom
footnoteReference/footnoteDefinitionhandlers plus a footer built fromstate.footnoteOrder, which also makes the package independent of upstream markup changes. - The duplicate-reference and renumber logic can be simplified because v13 handles both in document order.
- Replace the local
mergePluginscopy andunified.Pluginwith named types.
- Rewrite the selectors and the call / backlink rewriting against the v13 footer, or (preferred) stop post-processing the default footer and emit the Pandoc structure from custom
-
Tests
tests/pandoc.test.tscompares HTML after the full pipeline. All expectations depend on the chosen output and theclobberPrefixdecision.
remark-sectionize
Source: packages/remark-sectionize/src/section.ts.
- Mechanism
- mdast transformer. Visits headings from depth 6 to 1 and wraps each heading and its following siblings in a
sectionnode withdata.hName/data.hProperties. Reads the original heading line from the source viapositionoffsets to detect closing hashes (## Title ##opts out of sectioning) and end marks (##alone closes a section).
- mdast transformer. Visits headings from depth 6 to 1 and wraps each heading and its following siblings in a
- Coupling
ContentandHTMLfrom@types/mdast3 (RootContentandHtmlin 4)unist-util-find-after4 andunist-util-visit-parents5 (5 and 6 now)vfile4file.toString()(still works in 6)heading.data.hProperties.hidden, whichremark-attrsets from{hidden}, so it follows the attr rewrite- Augments
BlockContentMapandunistData. - A leftover
node.type === 'export'check is from MDX-era remark and matches nothing.
- Change
- Adapt types and utility majors. Verify in Phase 4 that micromark gives the same
positionfor headings with closing sequences and for bare##lines, because the opt-out and end-mark detection read the source text, not the AST.
- Adapt types and utility majors. Verify in Phase 4 that micromark gives the same
- Tests
tests/utils.tsusesremark-attrfor{hidden}andremark-parse8 options;rehype-formatandremark-attrare imported with@ts-expect-error.
mdast-to-hast-table-cell
Source: packages/mdast-to-hast-table-cell/src/index.ts.
- Mechanism
withTableCellTransform(hook)(handler)wraps atablehandler, runs it, collects everyth/tdin the result, and replaces each cell with the hook's output. Hooks receive{ h }and a cell context (node,tagName,align,properties,children). The three presets move thealignattribute to an attribute, a class, or an inline style.
- Coupling
HandHandlertypes frommdast-util-to-hast11; the wrapper and hooks are(h, node, parent).- Reads
cell.properties.align, which the v13tableRowhandler still sets, so the cell detection holds. - Tests deep-import
mdast-util-to-hast/lib/handlers/table.js, which v13 closes withexports; v13 exportsdefaultHandlers.tablefrom the root. hast-util-get-attribute1 andhast-util-get-class-list1 have no newer major.
- Change
- Adapt the wrapper to
(state, node, parent)and passstate(or a narrowed subset) to hooks instead ofh. This changes the publicTableCellHooktype. - Replace the deep import in tests with
defaultHandlers.table. - Remove
tests/rehype-format.d.tsoncerehype-format5 ships types.
- Adapt the wrapper to
- Tests
tests/table.test.tsandtests/composition.test.tscompare HTML throughremark-parse8 +remark-rehype8; GFM tables come from remark-gfm in 13.
rehype-rewrite-extension
Source: packages/rehype-rewrite-extension/src/index.ts.
- Mechanism
- hast transformer. For each rule, selects elements with
hast-util-select, reads the property withhast-util-get-attribute, rewrites the URI path extension withuri-js/upath, and writes it back.
- hast transformer. For each rule, selects elements with
- Coupling
hast-util-select5 (6 now). No remark or unified import.
- Change
- Keep; bump
hast-util-selectand@types/hast. Tests run the transformer directly on hand-built trees and need no change.
- Keep; bump
vfm-internal-utils
Source: packages/vfm-internal-utils/src/element-customizer.ts.
- Mechanism
buildElement(tagName, props, children, customizer)builds an element through hastscript, accepting either extra properties or a factory that receives a tag-awareh.HastPropertiesSchemais a valibot schema forhast.Properties.
- Coupling
- hastscript 7
h,Properties, andChildtypes. All calls pass an explicit properties object (h(tagName, props, ...children)), so the hastscript 9 child / properties ambiguity does not apply here, but factories supplied by users may hit it.
- hastscript 7
- Change
- Keep; bump hastscript and re-check the
TagAwareHoverloads against the hastscript 9 signature.
- Keep; bump hastscript and re-check the
External plugins
| Plugin | Used by | Current | Status in remark 13 | Decision |
|---|---|---|---|---|
| remark-attr | vfm (attr.ts), remark-sectionize tests |
0.11.1 | Unmaintained since 2020. Wraps every remark-parse 8 inline / block tokenizer to append {...} attributes. No micromark port. |
Write a VFM attribute extension (#46, #211). Prototype: origin/remark-attribute. Consumers: code.ts (attributes on fenced code), slug.ts ({#id} on headings), remark-sectionize ({hidden}), figure.ts ({alt=...}). |
| remark-shortcodes | vfm (toc.ts, metadata.ts) |
0.3.1 | Unmaintained. Patches Parser.prototype.blockTokenizers. |
Keep or drop [[toc]] per #207. If kept, a small micromark block extension or remark-directive 4 (::toc) replaces it. |
| remark-footnotes | vfm (footnotes.ts), footnote package tests |
2.0.0 | Deprecated. Patches Parser.prototype. remark-gfm 4 provides [^id] references and definitions but not inline notes ^[...]. |
Use remark-gfm for references / definitions. Write an inline-note micromark extension that emits the node the footnote packages consume. |
| remark-breaks | vfm (line-breaks.ts), remark-ruby tests |
1.0.5 | 4.0.0 is a plain mdast transformer with types. | Bump. |
| remark-frontmatter | vfm (revive-parse.ts, metadata.ts) |
2.0.0 | 5.0.0 is a micromark extension with types. | Bump. |
| remark-math | – | – | 6.0.0 (micromark-extension-math 3.1.0, mdast-util-math 3.0.0). Emits inlineMath / math nodes with value. |
Candidate to replace the math.ts tokenizer (#224). Node names and the value field differ from VFM's inlineMath / displayMath with data.value. |
| rehype-raw | vfm, dpub / sectionize / table-cell tests | 5.1.0 | 7.0.0 (hast-util-raw 9). |
Bump. |
| rehype-format | vfm (format.ts), all tests |
3.1.0 | 5.0.1 ships types. | Bump; delete the ambient declarations. |
| rehype-stringify | vfm, all tests | 8.0.0 | 10.0.1. | Bump. |
hast / unist utilities
| Package | Current | Target | Used by |
|---|---|---|---|
| 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, to be removed) |
| refractor | 3.6.0 | 5.0.0 | vfm (code.ts) |
| to-vfile / vfile | 6.1 / 4.0 | 8.0 / 6.0 | vfm, sectionize |
Order of work
- Define the VFM-owned node shapes first: inline note, ruby, attribute carrier,
[[toc]](if kept). The footnote packages,slug.ts,metadata.ts, andremark-sectionizeall read them. - Bump the shared hast / unist utilities and
hastscriptacross every package in one step, because the packages import each other throughworkspace:*. - Port
vfm-internal-utilsandrehype-rewrite-extension(Keep), thenmdast-to-hast-table-cellandremark-sectionize(Adapt), then the footnote packages, thenremark-ruby. - Rewrite each package's test utilities together with the package; they are the only place the remark-parse 8 options and
remark-footnotes/remark-attrdevDependencies remain.