日本語|English

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プラグイン(mdastPlugins slot)。
  • handler: remark-rehype に渡す mdast-util-to-hast のhandler (mdastToHastHandlers slot)。
  • hast: HTML AST上で動くunifiedプラグイン(hastPlugins slot)。
  • 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/mdast 4でキャストを直す必要がある。

モジュール インベントリ

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-format 5、remark-breaks 4、hast-util-find-and-replace 5は型を同梱する。
  • 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