remark 13移行: packages/vfm インベントリ
remark 13移行に向けた packages/vfm のモジュール単位のインベントリ(Phase 0-1, #277)。remark13-migration.mdの要約を展開したもので、Phase 2 / 3 / 4のIssueでチェックリストとして使うことを想定している。2026-10-17時点の main を対象に調査した。
以下で使うパイプラインの段階:
- mdast: Markdown AST上で動くunifiedプラグイン(
mdastPluginsslot)。 - handler:
remark-rehypeに渡すmdast-util-to-hastのhandler (mdastToHastHandlersslot)。 - hast: HTML AST上で動くunifiedプラグイン(
hastPluginsslot)。 - wrapper / schema:自身ではツリーに触れない。外部プラグインをラップするか、オプション スキーマを定義するだけ。
変更分類:
- Rewrite:仕組みそのものがremark 13に存在しない(旧tokenizer、unifiedの名前空間型、remark-parseのオプション)。
- Adapt:同じ仕組みが別のAPIで存在する(handler署名、型名変更、hastユーティリティのmajor更新)。
- Keep: remarkのバージョンに依存しない。共通の型パッケージの更新のみ。
プロセッサ構成
メイン プロセッサ(src/index.ts, VFM())
remark-parse { gfm, commonmark }
→ mdastPlugins (11 slot, revive-parse.ts)
→ inspect('mdast')
→ remark-rehype { allowDangerousHtml, handlers }
→ hastPlugins (8 slot, revive-rehype.ts)
→ inspect('hast')
→ rehype-stringify
| # | mdast slot (revive-parse.ts) |
出所 | 備考 |
|---|---|---|---|
| 1 | parseImageAltAsInline |
figure.ts | Image.alt を this.parse() で再パース |
| 2 | lineBreaks |
line-breaks.ts | hardLineBreaks 時にremark-breaks |
| 3 | math |
math.ts | 旧tokenizer。findAndReplace のフォールバックあり |
| 4 | ruby |
@vivliostyle/remark-ruby | 旧tokenizer |
| 5 | footnote |
footnotes.ts | remark-footnotes { inlineNotes: true } |
| 6 | attr |
attr.ts | remark-attr |
| 7 | slug |
slug.ts | data.hProperties.id を設定 |
| 8 | section |
@vivliostyle/remark-sectionize | |
| 9 | code |
code.ts | remark-attrが書いた属性を読む |
| 10 | toc |
toc.ts | remark-shortcodes +フィルター |
| 11 | frontmatter |
remark-frontmatter |
handler slot (revive-rehype.ts) |
出所 | 備考 |
|---|---|---|
displayMath |
math.ts | |
inlineMath |
math.ts | |
ruby |
@vivliostyle/remark-ruby | |
code |
code.ts | |
paragraph |
revive-rehype.ts | 合成: buildDisplayMath ?? buildFigure ??既定の <p> |
table |
mdast-to-hast-table-cell | deep importした既定の table handlerをラップ |
footnoteDefinition / footnoteReference / footnote |
footnoteパッケージ | undefined のエントリーは除外して既定handlerに委ねる |
| # | hast slot (revive-rehype.ts) |
出所 | 備考 |
|---|---|---|---|
| 1 | raw |
rehype-raw | |
| 2 | deriveImgAltFromFigcaption |
figure.ts | raw の後である必要がある |
| 3 | footnoteTransformer |
footnoteパッケージ | |
| 4 | replace |
replace.ts | |
| 5 | rewriteRelativeHrefExtensions |
@vivliostyle/rehype-rewrite-extension | |
| 6 | document |
document.ts | ツリーを <html> で包む。partial 時はスキップ |
| 7 | math |
math.ts | document の後である必要がある(<head> に書く) |
| 8 | format |
format.ts | disableFormatHtml でなければrehype-format |
VFM() のその他の特徴:
.data('settings', { position: true })をremark-parse 8に渡している。remark-parse 11にはposition設定が無く、positionは常に付く。editPluginsフックは3つのリストを受け取り、任意のpluggableリストを返せる。ブランドslot型(brand<T>())は名目的なもので、SemVerの契約ではないと明記されている。undefinedのhandlerエントリーはremark-rehypeに渡す前に除外し、既定handlerを上書きしないようにしている。
2本目のプロセッサ(src/plugins/metadata.ts, readMetadata())
remark-parse { gfm, commonmark } → footnotes → attr → frontmatter → mdast (metadata reader)
→ remark-rehype → rehype-stringify
- frontmatter YAML、最初の見出し、
[[toc]]からvfile.dataを埋めるためだけに存在する。HTML出力は捨てる。 .data('settings', { position: false })はremark 13では効果が無い。- プラグイン リストを
unified.PluggableList<unified.Settings>にキャストしている。unified 11ではこの名前空間型が消える。 unist-util-selectによる見出し検索をhastのElementとして型付けしているが、ツリーはmdast。実行時には無害だが、@types/mdast4でキャストを直す必要がある。
モジュール インベントリ
src/plugins/
| ファイル | 段階 | export | remark 8依存 | 変更 |
|---|---|---|---|---|
attr.ts |
wrapper | mdast |
remark-attr 0.11が Parser.prototype のtokenizerを書き換える。更新停止。 |
Rewrite。micromark / mdast拡張として自作する(#46, #211)。先行試作は origin/remark-attribute。 |
code.ts |
mdast + handler | mdast, handler, CodeOptionsSchema, CodeOptions |
code ノードを visit。meta が空のときremark-attrが書く hProperties を削除する("bad hack"対策)。refractor.highlight() はv3では配列を返す。handlerは (h, node) で h(node.position, tag, props, children) を呼ぶ。unist の Data に hName / hProperties / hChildren / figcaptionTitle をaugmentation。 |
Adapt。attrの書き直しに合わせてremark-attr対策を削る。refractor 5は Root を返すので .children を取る。handlerは (state, node) にし、state.patch / state.applyData で要素を組む。augmentationは figcaptionTitle だけ残す(他は mdast-util-to-hast 13が提供)。 |
document.ts |
hast | mdast (歴史的な名前。実際はhast上で動く), DocumentSerializableOptionsSchema, DocumentOptions |
doctype ノードとhastscript 7で組んだ <html> を持つ新しいrootを返す。h('head', ...children) とchildrenを可変長引数で渡している。vfile.stem とグローバル型 KeyValue を使う。 |
Adapt。hastscript 9は最初の非文字列引数をpropertiesと解釈するので、childrenは1つの配列で渡す。slot APIを見直す際にexport名を変えるか hast の別名を付ける。 |
figure.ts |
mdast + handlerヘルパー+ hast | mdast (parseImageAltAsInline), buildFigure, hast (deriveImgAltFromFigcaption), FigureOptionsSchema, FigcaptionInlineOptionsSchema,オプション型 |
this.parse(image.alt) はremark-parse 8が alt に生のMarkdownソースを保持することに依存する。micromarkは alt をプレーンテキストにdecodeするため、プラグインが動く前にキャプション内のインライン記法が失われる。buildFigure は H を受け取り mdast-util-to-hast 11の one(h, ...) / all(h, ...) を呼ぶ。Image ノードに非標準の children を付ける。parseHtml は hast-util-raw 6 (raw(tree))を使う。 |
altの再パースはRewrite: alt を再パースするのではなく、micromark / from-markdown層で生のキャプション ソースを捕捉する(例:拡張がソース テキストを data に記録する)。buildFigure は state.one() / state.all() に、hast-util-raw 9 (raw(tree, options))にAdapt。Image.children の慣習は @types/mdast 4の下で型付きノードまたは data フィールドにする。 |
footnotes.ts |
wrapper | mdast, createFootnotePlugin, FootnoteModeSchema, FootnoteOptionsSchema, YamlFootnoteOptionsSchema, factory型の再export |
remark-footnotes 2 (旧tokenizer、deprecated)を inlineNotes: true で使う。handlerが (h, node) のfootnote 3パッケージへ振り分ける。モジュール コメントが mdast-util-to-hast 10 / 11の二重依存を記述している。 |
パーサー側はRewrite: remark-gfm 4は footnoteDefinition / footnoteReference を提供するがinline note ^[...] は無いので、inline note拡張が必要(再作成しなければ footnote ノード型は消える)。handlerの振り分けはfootnoteパッケージと一緒にv13署名へAdapt。mdast-util-to-hast 13が生成するendnote構造(<section data-footnotes>、user-content- 接頭辞、clobberPrefix)はv10と異なり、pandocパッケージを左右する。 |
format.ts |
wrapper | hast, FormatOptionsSchema, FormatOptions |
rehype-format 3。ambientな declare module で型付け。 |
Adapt: rehype-format 5は型を同梱する。ambient宣言を削除。 |
line-breaks.ts |
wrapper | mdast, LineBreaksOptionsSchema, LineBreaksOptions |
remark-breaks 1は Parser.prototype を書き換える。ambientな declare module で型付け。 |
Adapt: remark-breaks 4は型付きの通常のmdast transformer。 |
math.ts |
mdast (tokenizer) + handler + hast | mdast, handlerInlineMath, handlerDisplayMath, buildDisplayMath, hast, MathRendererSchema, MathOptionsSchema,オプション型 |
types/remark.d.ts のグローバル型 Tokenizer を使って inlineMath / displayMath を Parser.prototype.inlineTokenizers / inlineMethods に追加する。「remark 13以降」向けの findAndReplace フォールバックがあるが、パース後に動くため $...$ 内の **x** はすでに strong になっており等価ではない。handlerは (h, node) で node.data.value を読む。StaticPhrasingContentMap をaugmentation。 |
パーサー側はmicromark拡張としてRewrite (候補はremark-math 6、#224。inlineMath / math ノードを data.value ではなく value で出す)。findAndReplace フォールバックは削除。handlerは (state, node) と PhrasingContentMap にAdapt。hast段(MathJax <script> 注入、temml出力)は影響なし。 |
metadata.ts |
mdast (独自プロセッサ) | readMetadata, VFMSettingsSchema, VFMSettings, Metadata, Attribute |
上記「2本目のプロセッサ」を参照。加えて visit(tree, 'shortcode') はremark-shortcodesのノード型に依存。readTitleFromHeading は footnote 子要素(inline note)を除外し、その時点ではルビがパースされていないため正規表現でルビ記法を取り除く。 |
プロセッサ構築をAdapt (import { unified }、remark-gfm、parseオプション無し、PluggableList キャスト無し)。除外するノード型は toc とinline footnoteの決定に従う。 |
options.ts |
schema | SerializablePluginOptionsSchema, SerializablePluginOptions |
なし。 | Keep。 |
replace.ts |
hast | replace, ReplaceRuleSchema, ReplaceOptionsSchema, ReplaceRule, ReplaceOptions |
hast-util-find-and-replace 3のdefault import、ambientな declare module で型付け。ユーザー コールバックにhastscriptの h を渡すので typeof h が公開API。 |
Adapt: v5は findAndReplace を名前付きexportし、同じ [find, replace] のリスト形式を受け付ける。hastscript 9でユーザー コールバックが見る h の型が変わる。ReplaceRule 固定に関する @todo を見直す。 |
rewrite-relative-href-extensions.ts |
schema + resolver | RewriteRelativeHrefExtensionsOptionsSchema, resolveRewriteRelativeHrefExtensions,オプション型 |
なし。hast処理は @vivliostyle/rehype-rewrite-extension にある。 |
Keep。 |
slug.ts |
mdast | mdast |
unist-util-select 4と mdast-util-to-string 3。footnote 子要素(inline note)を除外。heading.data.id と heading.data.hProperties.id を書く。 |
ユーティリティのmajor更新にAdapt。footnotes.ts で選ぶinline footnoteノード型と同期する。 |
table.ts |
schema + hook adapter | resolveTableCellHook, TableOptionsSchema, YamlTableOptionsSchema, TableCell* スキーマと型 |
直接の依存なし。@vivliostyle/mdast-to-hast-table-cell と @vivliostyle/vfm-internal-utils に依存。 |
Keep。型は @types/hast 3に従う。 |
toc.ts |
wrapper + mdast | mdast, Shortcode |
remark-shortcodes 0.3が Parser.prototype.blockTokenizers を書き換える(旧tokenizer、更新停止、ambientな declare module で型付け)。keepToC が [[toc]] 以外のshortcodeを除去する。BlockContentMap をaugmentation。 |
#207に従ってRewriteまたは廃止。残す場合は [[toc]] 用のmicromark拡張(またはdirectiveベースの構文)が必要。metadata.ts が同じノード型に依存する。 |
src/
| ファイル | 役割 | remark 8依存 | 変更 |
|---|---|---|---|
index.ts |
VFM() と stringify() の構築。スキーマ、型、ブランド型の再export |
import unified, { type Processor } from 'unified'。[remarkParse, { gfm: true, commonmark: true }]。EditedPlugins が unified.Pluggable を使う。settings.position。 |
importをRewrite (import { unified } from 'unified'、Pluggable / Processor を名前付き型で)。parseオプションをmdast slotリストのremark-gfmに置き換える。editPlugins がブランドslotを公開し続けるか決める。 |
revive-parse.ts |
mdast 11 slotとブランド型の組み立て | unified.Pluggable 名前空間型(ブランド宣言11件)。 |
名前付き Pluggable にAdapt。attr / math / footnote / tocの書き直しとremark-gfm追加でslotリストが変わる。 |
revive-rehype.ts |
handlerとhast 8 slotの組み立て | import { type Handler, all } from 'mdast-util-to-hast'。deep import mdast-util-to-hast/lib/handlers/table.js。合成 paragraph handlerは (h, node)。unified.Pluggable (ブランド宣言8件)。 |
Adapt。v13はパッケージ ルートから defaultHandlers.table をexportしておりdeep importは閉じられる。paragraph handlerは state.all() を使う (state, node) になる。 |
utils.ts |
debug, inspect, partial, brand, mergePlugins, StripFunctions |
unified.Plugin / unified.Pluggable 名前空間型。partial はattacherが this.Parser を読めるように this を転送する。 |
型をAdapt。partial の this 転送は残してよい(無害)が、旧tokenizerが消えれば理由はなくなる。 |
cli.ts |
CLI (meow) | なし。 | Keep。 |
types/remark.d.ts
型の無い依存(hast-util-find-and-replace, remark-shortcodes, rehype-format, remark-breaks, remark-attr, md-attr-parser)のambient宣言、remark-parse 8の Tokenizer / TokenizerInstance の形、グローバルの KeyValue 別名。
Tokenizer型は旧tokenizerとともに消える。rehype-format5、remark-breaks4、hast-util-find-and-replace5は型を同梱する。remark-shortcodesとremark-attrは書き直しまたは廃止で消える。KeyValueとmd-attr-parserの宣言は残すか、使うモジュールへ移す。
module augmentationの箇所
| ファイル | 対象 | remark 13での対応物 |
|---|---|---|
src/plugins/code.ts |
unist Data (hName, hProperties, hChildren, figcaptionTitle) |
mdast-util-to-hast 13が先の3つで Data をaugmentationする |
src/plugins/math.ts |
mdast StaticPhrasingContentMap |
@types/mdast 4の PhrasingContentMap |
src/plugins/toc.ts |
mdast BlockContentMap |
BlockContentMap のまま。shortcode 型はtocの決定に従う |
types/remark.d.ts |
ambientモジュールとグローバル | 上記参照 |
テスト
| ファイル | 依存 | 影響 |
|---|---|---|
tests/utils.ts |
VFM().freeze(), vfm.parse(), positionと data: 行を除いた unist-util-inspect ダンプ |
MDAST比較はダンプ文字列による。ノード形状の変化(remark-mathの inlineMath、remark-gfmのfootnote、属性ノードなど)はすべて期待文字列の書き直しになる。HTML比較は原則として影響なし。 |
tests/defs.test.ts |
vfm.Parser.prototype.inlineMethods / blockMethods / interrupt* |
移植不能。micromark拡張リストのテストに置き換えるか削除する。 |
tests/edit-plugins.test.ts |
unified 名前空間型、ブランド型、両ツリーでの visit |
unified 11への型レベルの適応。挙動は維持されるはず。 |
tests/math.test.ts, tests/math-mathml.test.ts |
inlineMath / displayMath のダンプ、data.value |
remark-math採用でノード形状が変わる(data.value → value、displayMath → math)。 |
tests/figure.test.ts (最大のファイル) |
alt再パース、Image.children、段落内のHTMLコメント |
figureの書き直しに従う。コメント処理(isHtmlComment)はmicromarkが段落内で html ノードをどう出すかに依存する。 |
tests/footnotes.test.ts |
remark-footnotesのノード ダンプ、3つの出力モード | footnoteの書き直しに従う。mdast-util-to-hast 13のendnote構造。 |
tests/attr.test.ts, tests/code.test.ts |
remark-attrの出力。hProperties のダンプは除外される |
attrの書き直しが忠実ならHTML期待値は維持される。 |
tests/metadata.test.ts |
readMetadata のみ |
見出しからのタイトル抽出(footnote / 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 table、remark-breaks、rehype-format、document wrapper、allowDangerousHtml + rehype-raw |
挙動レベルの検証。rehype-format 5による整形差と、markdown-inside-html でのmicromarkの空白差を見込む。 |
変更分類ごとのまとめ
| 変更 | モジュール |
|---|---|
| Rewrite | attr, math (パーサー側), footnotes (inline note), toc (または廃止), figure (alt再パース), index (import / parseオプション) |
| Adapt | code, document, figure (handler + hast), footnotes (handler振り分け), format, line-breaks, metadata, replace, slug, revive-parse, revive-rehype, utils, types/remark.d.ts |
| Keep | options, rewrite-relative-href-extensions, table, cli |