remark 13 Migration: packages/vfm Inventory
Module-by-module inventory of packages/vfm for the remark 13 migration (Phase 0-1, #277). It expands the summary in remark13-migration.md and is meant to be used as a checklist by the Phase 2 / 3 / 4 issues. Surveyed against main as of 2026-10-17.
Pipeline stages used below:
- mdast: a unified plugin that runs on the Markdown AST (
mdastPluginsslot). - handler: an
mdast-util-to-hasthandler passed toremark-rehype(mdastToHastHandlersslot). - hast: a unified plugin that runs on the HTML AST (
hastPluginsslot). - wrapper / schema: no tree access of its own. Wraps an external plugin or only defines option schemas.
Change class:
- Rewrite: the mechanism no longer exists in remark 13 (legacy tokenizers, unified namespace types, remark-parse options).
- Adapt: the same mechanism exists with a different API (handler signature, renamed types, major bumps of hast utilities).
- Keep: no remark version coupling. Only the shared type packages move.
Processor composition
Main processor (src/index.ts, VFM())
remark-parse { gfm, commonmark }
→ mdastPlugins (11 slots, revive-parse.ts)
→ inspect('mdast')
→ remark-rehype { allowDangerousHtml, handlers }
→ hastPlugins (8 slots, revive-rehype.ts)
→ inspect('hast')
→ rehype-stringify
| # | mdast slot (revive-parse.ts) |
Source | Note |
|---|---|---|---|
| 1 | parseImageAltAsInline |
figure.ts | Re-parses Image.alt through this.parse() |
| 2 | lineBreaks |
line-breaks.ts | remark-breaks when hardLineBreaks |
| 3 | math |
math.ts | Legacy tokenizer; findAndReplace fallback |
| 4 | ruby |
@vivliostyle/remark-ruby | Legacy tokenizer |
| 5 | footnote |
footnotes.ts | remark-footnotes { inlineNotes: true } |
| 6 | attr |
attr.ts | remark-attr |
| 7 | slug |
slug.ts | Sets data.hProperties.id |
| 8 | section |
@vivliostyle/remark-sectionize | |
| 9 | code |
code.ts | Reads attributes written by remark-attr |
| 10 | toc |
toc.ts | remark-shortcodes + filter |
| 11 | frontmatter |
remark-frontmatter |
Handler slot (revive-rehype.ts) |
Source | Note |
|---|---|---|
displayMath |
math.ts | |
inlineMath |
math.ts | |
ruby |
@vivliostyle/remark-ruby | |
code |
code.ts | |
paragraph |
revive-rehype.ts | Composite: buildDisplayMath ?? buildFigure ?? default <p> |
table |
mdast-to-hast-table-cell | Wraps the default table handler imported via deep import |
footnoteDefinition / footnoteReference / footnote |
footnote packages | undefined entries are stripped to fall back to the defaults |
| # | hast slot (revive-rehype.ts) |
Source | Note |
|---|---|---|---|
| 1 | raw |
rehype-raw | |
| 2 | deriveImgAltFromFigcaption |
figure.ts | Must follow raw |
| 3 | footnoteTransformer |
footnote packages | |
| 4 | replace |
replace.ts | |
| 5 | rewriteRelativeHrefExtensions |
@vivliostyle/rehype-rewrite-extension | |
| 6 | document |
document.ts | Wraps the tree in <html>; skipped when partial |
| 7 | math |
math.ts | Must follow document (writes <head>) |
| 8 | format |
format.ts | rehype-format unless disableFormatHtml |
Other characteristics of VFM():
.data('settings', { position: true })is passed to remark-parse 8. remark-parse 11 has nopositionsetting; positions are always attached.- The
editPluginshook receives the three lists and may return any pluggable lists. The branded slot types (brand<T>()) are nominal only and are documented as not being a SemVer contract. undefinedhandler entries are stripped before they reachremark-rehypeso that the default handlers are not overwritten.
Second processor (src/plugins/metadata.ts, readMetadata())
remark-parse { gfm, commonmark } → footnotes → attr → frontmatter → mdast (metadata reader)
→ remark-rehype → rehype-stringify
- Exists only to populate
vfile.datafrom frontmatter YAML, the first heading, and[[toc]]. The HTML output is discarded. .data('settings', { position: false })has no effect in remark 13.- The plugin list is cast to
unified.PluggableList<unified.Settings>, a namespace type that disappears with unified 11. - The heading lookup via
unist-util-selectis typed as a hastElementalthough the tree is mdast. Harmless at runtime, but the cast must change with@types/mdast4.
Module inventory
src/plugins/
| File | Stage | Exports | remark 8 coupling | Change |
|---|---|---|---|---|
attr.ts |
wrapper | mdast |
remark-attr 0.11 patches Parser.prototype tokenizers. Unmaintained. |
Rewrite as a micromark / mdast extension (#46, #211). Prototype in origin/remark-attribute. |
code.ts |
mdast + handler | mdast, handler, CodeOptionsSchema, CodeOptions |
visit on code nodes; deletes hProperties that remark-attr writes when meta is empty ("bad hack" workaround); refractor.highlight() returns an array in v3; handler is (h, node) and calls h(node.position, tag, props, children); augments unist Data with hName / hProperties / hChildren / figcaptionTitle. |
Adapt. Drop the remark-attr workaround with the attr rewrite. refractor 5 returns a Root, take .children. Handler becomes (state, node) and builds elements with state.patch / state.applyData. Keep only the figcaptionTitle augmentation; mdast-util-to-hast 13 ships the rest. |
document.ts |
hast | mdast (name is historical; it runs on hast), DocumentSerializableOptionsSchema, DocumentOptions |
Returns a new root with a doctype node and an <html> built by hastscript 7. h('head', ...children) spreads the children as positional arguments. Uses vfile.stem and the global KeyValue type. |
Adapt. hastscript 9 treats the first non-string argument as properties, so children must be passed as one array. Rename the export or alias it as hast when the slot API is revisited. |
figure.ts |
mdast + handler helper + hast | mdast (parseImageAltAsInline), buildFigure, hast (deriveImgAltFromFigcaption), FigureOptionsSchema, FigcaptionInlineOptionsSchema, option types |
this.parse(image.alt) relies on remark-parse 8 keeping alt as raw Markdown source. micromark decodes alt to plain text, so inline markup in a caption is lost before the plugin runs. buildFigure takes H and calls one(h, ...) / all(h, ...) from mdast-util-to-hast 11. Attaches non-standard children to an Image node. parseHtml uses hast-util-raw 6 (raw(tree)). |
Rewrite the alt re-parse: capture the raw caption source in the micromark / from-markdown layer (for example as an extension that records the source text in data) instead of re-parsing alt. Adapt buildFigure to state.one() / state.all(), and hast-util-raw 9 (raw(tree, options)). The Image.children convention needs a typed node or data field under @types/mdast 4. |
footnotes.ts |
wrapper | mdast, createFootnotePlugin, FootnoteModeSchema, FootnoteOptionsSchema, YamlFootnoteOptionsSchema, re-exported factory types |
remark-footnotes 2 (legacy tokenizer, deprecated) with inlineNotes: true. Dispatches to the three footnote packages whose handlers are (h, node). The module comment documents the double mdast-util-to-hast 10 / 11 dependency. |
Rewrite the parser side: remark-gfm 4 provides footnoteDefinition / footnoteReference but not inline notes ^[...], so an inline-note extension is required (the footnote node type disappears unless it is re-created). Adapt the handler dispatch to the v13 signature together with the footnote packages. The endnote structure generated by mdast-util-to-hast 13 (<section data-footnotes>, user-content- prefix, clobberPrefix) differs from v10 and drives the pandoc package. |
format.ts |
wrapper | hast, FormatOptionsSchema, FormatOptions |
rehype-format 3, typed through an ambient declare module. |
Adapt: rehype-format 5 ships types. Remove the ambient declaration. |
line-breaks.ts |
wrapper | mdast, LineBreaksOptionsSchema, LineBreaksOptions |
remark-breaks 1 patches Parser.prototype; typed through an ambient declare module. |
Adapt: remark-breaks 4 is a plain mdast transformer with types. |
math.ts |
mdast (tokenizer) + handler + hast | mdast, handlerInlineMath, handlerDisplayMath, buildDisplayMath, hast, MathRendererSchema, MathOptionsSchema, option types |
Adds inlineMath / displayMath to Parser.prototype.inlineTokenizers / inlineMethods using the global Tokenizer type from types/remark.d.ts. Has a findAndReplace fallback for "remark 13 or later", but that runs after parsing, so **x** inside $...$ is already strong and the fallback is not equivalent. Handlers are (h, node) and read node.data.value. Augments StaticPhrasingContentMap. |
Rewrite the parser side as a micromark extension (remark-math 6 is the candidate, #224; it emits inlineMath / math nodes with value, not data.value). Delete the findAndReplace fallback. Adapt handlers to (state, node) and PhrasingContentMap. The hast stage (MathJax <script> injection, temml output) is unaffected. |
metadata.ts |
mdast (own processor) | readMetadata, VFMSettingsSchema, VFMSettings, Metadata, Attribute |
See "Second processor" above. Also: visit(tree, 'shortcode') depends on the remark-shortcodes node type; readTitleFromHeading filters footnote children (inline notes) and strips ruby syntax with a regex because ruby is not parsed at that point. |
Adapt the processor construction (import { unified }, remark-gfm, no parse options, no PluggableList cast). Follow the toc and inline footnote decisions for the node types it filters. |
options.ts |
schema | SerializablePluginOptionsSchema, SerializablePluginOptions |
None. | Keep. |
replace.ts |
hast | replace, ReplaceRuleSchema, ReplaceOptionsSchema, ReplaceRule, ReplaceOptions |
hast-util-find-and-replace 3 default import, typed through an ambient declare module. Hands hastscript h to user callbacks, so typeof h is public API. |
Adapt: v5 exports findAndReplace by name and accepts the same [find, replace] list form; hastscript 9 changes the h typing that user callbacks see. Review the @todo about pinning ReplaceRule. |
rewrite-relative-href-extensions.ts |
schema + resolver | RewriteRelativeHrefExtensionsOptionsSchema, resolveRewriteRelativeHrefExtensions, option type |
None. The hast work is in @vivliostyle/rehype-rewrite-extension. |
Keep. |
slug.ts |
mdast | mdast |
unist-util-select 4 and mdast-util-to-string 3; filters footnote children (inline notes); writes heading.data.id and heading.data.hProperties.id. |
Adapt the utility majors. Keep in sync with the inline footnote node type chosen for footnotes.ts. |
table.ts |
schema + hook adapter | resolveTableCellHook, TableOptionsSchema, YamlTableOptionsSchema, TableCell* schemas and types |
None directly. Depends on @vivliostyle/mdast-to-hast-table-cell and @vivliostyle/vfm-internal-utils. |
Keep; types follow @types/hast 3. |
toc.ts |
wrapper + mdast | mdast, Shortcode |
remark-shortcodes 0.3 patches Parser.prototype.blockTokenizers (legacy tokenizer, unmaintained, typed through an ambient declare module). keepToC removes every shortcode except [[toc]]. Augments BlockContentMap. |
Rewrite or drop per #207. If kept, [[toc]] needs its own micromark extension (or a directive-based syntax). metadata.ts depends on the same node type. |
src/
| File | Role | remark 8 coupling | Change |
|---|---|---|---|
index.ts |
Builds VFM() and stringify(); re-exports schemas, types, and brand types |
import unified, { type Processor } from 'unified'; [remarkParse, { gfm: true, commonmark: true }]; EditedPlugins uses unified.Pluggable; settings.position. |
Rewrite the imports (import { unified } from 'unified', Pluggable / Processor as named types). Replace the parse options with remark-gfm in the mdast slot list. Decide whether editPlugins keeps exposing branded slots. |
revive-parse.ts |
Assembles the 11 mdast slots and their brand types | unified.Pluggable namespace type (11 brand declarations). |
Adapt to named Pluggable. Slot list changes with the attr / math / footnote / toc rewrites and the addition of remark-gfm. |
revive-rehype.ts |
Assembles the handlers and 8 hast slots | import { type Handler, all } from 'mdast-util-to-hast'; deep import mdast-util-to-hast/lib/handlers/table.js; the composite paragraph handler is (h, node); unified.Pluggable (8 brand declarations). |
Adapt. v13 exports defaultHandlers.table from the package root, closing the deep import. The paragraph handler becomes (state, node) with state.all(). |
utils.ts |
debug, inspect, partial, brand, mergePlugins, StripFunctions |
unified.Plugin / unified.Pluggable namespace types. partial forwards this specifically so attachers can read this.Parser. |
Adapt the types. partial can keep forwarding this (harmless) but the reason for it disappears with the legacy tokenizers. |
cli.ts |
CLI (meow) | None. | Keep. |
types/remark.d.ts
Ambient declarations for untyped dependencies (hast-util-find-and-replace, remark-shortcodes, rehype-format, remark-breaks, remark-attr, md-attr-parser), the remark-parse 8 Tokenizer / TokenizerInstance shape, and the global KeyValue alias.
- The
Tokenizertypes go away with the legacy tokenizers. rehype-format5,remark-breaks4, andhast-util-find-and-replace5 ship their own types.remark-shortcodesandremark-attrdisappear with their rewrite or removal.KeyValueand themd-attr-parserdeclaration can stay or move into the module that uses them.
Module augmentation sites
| File | Target | remark 13 counterpart |
|---|---|---|
src/plugins/code.ts |
unist Data (hName, hProperties, hChildren, figcaptionTitle) |
mdast-util-to-hast 13 augments Data with the first three |
src/plugins/math.ts |
mdast StaticPhrasingContentMap |
PhrasingContentMap in @types/mdast 4 |
src/plugins/toc.ts |
mdast BlockContentMap |
Still BlockContentMap; the shortcode type follows the toc decision |
types/remark.d.ts |
Ambient modules and globals | See above |
Tests
| File | Depends on | Impact |
|---|---|---|
tests/utils.ts |
VFM().freeze(), vfm.parse(), unist-util-inspect dumps with position and data: lines stripped |
The MDAST comparison is by dump string. Any node shape change (for example inlineMath from remark-math, remark-gfm footnotes, attribute nodes) rewrites the expected strings. HTML comparison is unaffected in principle. |
tests/defs.test.ts |
vfm.Parser.prototype.inlineMethods / blockMethods / interrupt* |
Cannot be ported. Replace with tests on the micromark extension list or drop. |
tests/edit-plugins.test.ts |
unified namespace types, brand types, visit on both trees |
Type-level adaptation to unified 11; behavior should hold. |
tests/math.test.ts, tests/math-mathml.test.ts |
inlineMath / displayMath dumps, data.value |
Node shape changes with remark-math (value instead of data.value, math instead of displayMath). |
tests/figure.test.ts (largest file) |
Alt re-parse, Image.children, HTML comments inside the paragraph |
Follows the figure rewrite. The comment handling (isHtmlComment) depends on how micromark emits html nodes inside paragraphs. |
tests/footnotes.test.ts |
remark-footnotes node dumps, three output modes | Follows the footnote rewrite; endnote structure of mdast-util-to-hast 13. |
tests/attr.test.ts, tests/code.test.ts |
remark-attr output, hProperties dumps are stripped |
HTML expectations hold if the attr rewrite is faithful. |
tests/metadata.test.ts |
readMetadata only |
Mostly independent of the parser, except title extraction from headings with footnotes / ruby. |
tests/table.test.ts, tests/line-breaks.test.ts, tests/html-formatter.test.ts, tests/html-lang.test.ts, tests/markdown-inside-html.test.ts, tests/rewrite-relative-href-extensions.test.ts, tests/index.test.ts |
GFM tables, remark-breaks, rehype-format, document wrapper, allowDangerousHtml + rehype-raw |
Behavior-level checks. Expect formatting differences from rehype-format 5 and whitespace differences from micromark in markdown-inside-html. |
Summary by change class
| Change | Modules |
|---|---|
| Rewrite | attr, math (parser side), footnotes (inline notes), toc (or removal), figure (alt re-parse), index (imports / parse options) |
| Adapt | code, document, figure (handler + hast), footnotes (handler dispatch), format, line-breaks, metadata, replace, slug, revive-parse, revive-rehype, utils, types/remark.d.ts |
| Keep | options, rewrite-relative-href-extensions, table, cli |