MdFlow

Appearance

Appendix C — Migration Notes ​

This appendix is informative. It sketches migration paths into and out of MdFlow for authors and implementers.

C.1 From CommonMark ​

Source text ​

Most CommonMark source parses identically in MdFlow. The notable compatibility concerns:

  1. Raw HTML. If your source contains <div>...</div>, <span>..., <iframe>, etc., those will render as literal text in MdFlow. Rewrite to custom elements (<md-div>, <md-container>) after registering an appropriate extension.
  2. Setext headings. Rewrite Title\n===== to # Title.
  3. Reference links. Rewrite [text][label] + [label]: url into inline [text](url).
  4. Numeric entities. Replace &#169; with &copy; or with the literal character U+00A9.
  5. Emphasis corner cases. If your source relies on CommonMark's nested emphasis resolution of ***foo*** + punctuation, test against MdFlow's greedy matcher. Simple cases are identical.

Implementation ​

An existing CommonMark parser can be adapted to MdFlow by:

  1. Disabling raw HTML passthrough (remove the raw HTML parser phase).
  2. Disabling setext heading parsing.
  3. Disabling reference link lookup.
  4. Adding pipe-table and strikethrough handling (common extensions — most parsers already support them).
  5. Adding the custom-element parser per §8.
  6. Enforcing the URL scheme filter per §10.3.1.1.
  7. Running the @mdflow/spec-tests conformance suite.

A pure-CommonMark parser that adds (1), (7) only claims Class B conformance for the MdFlow-subset vectors; streaming requires additional work (re-entrant tokenization, pending-token support).

C.2 From Markdown-It / Marked / Remark ​

Similar considerations to C.1. Most plugin-based markdown libraries can implement MdFlow by:

  1. Enabling GFM (tables, strikethrough).
  2. Disabling raw HTML.
  3. Disabling reference links (or accepting divergence in Class B only).
  4. Wiring the URL filter.
  5. Adding a custom-element plugin for md-* tags.

For streaming conformance, these libraries typically require an adapter that accumulates chunks and re-parses at block boundaries — acceptable for Class S conformance, though less efficient than native pending-token support.

C.3 Between MdFlow versions ​

v1.0 → v1.1 (planned) ​

v1.1 is planned to add:

  • Reference-style link definitions.
  • Task list items.
  • Footnotes.

These will be ADDITIVE: v1.0-conformant source continues to parse the same way. Implementations conforming to v1.0 remain conformant; they simply do not recognize the new constructs.

v1.x → v2.0 (no timeline) ​

v2.0 is the earliest version that MAY introduce breaking changes. Breaking changes will be rare and listed individually; upgrade guides will accompany any v2 release.

C.4 Escape hatches ​

For niche syntactic needs not covered by the core plus registered extensions, authors SHOULD:

  1. Propose the syntax via an extension RFC.
  2. In the interim, embed the niche content in a code block with an info string indicating a post-processor.
  3. Use a custom element with opaque text children (e.g., <md-raw> whose content is treated verbatim).

Do NOT use unescaped <script> or <style> — these are deliberately inert.

C.5 Testing migration ​

The MdFlow conformance suite includes a commonmark/ subdirectory of vectors imported from CommonMark v0.31.2. Implementations tracking both standards SHOULD run this suite alongside the core MdFlow suite and publish the delta.