MdFlow

Appearance

The MdFlow Standard ​

Version 1.0 · Working Draft · 2026-04-15

This is the authoritative specification of MdFlow, an independent standard for streaming markdown rendering with formally safe inclusion of custom HTML elements. MdFlow is a peer to, not a fork of, CommonMark: where semantics overlap, MdFlow aspires to produce output byte-identical to a CommonMark-conformant parser; where they diverge, divergences are enumerated in Appendix B.

Status of this document. This is a draft of the v1.0 specification. Normative clauses are stable; prose and examples may be refined up to the v1.0 release. Implementers targeting v1.0 SHOULD track the change log.

Reading order ​

The chapters are authored to be read in order. Implementers in a hurry can skip to §2 Conformance, §5 Streaming Model, and §10 Security Model — these three chapters carry the bulk of the normative weight unique to MdFlow.

Table of contents ​

Part I — Foundations ​

  1. Introduction & Scope
  2. Conformance
  3. Document Model
  4. Lexical Structure
  5. Streaming Model

Part II — Syntax ​

  1. Block Syntax
  2. Inline Syntax
  3. HTML & Custom Elements

Part III — Mechanisms ​

  1. Extension Mechanism
  2. Security Model
  3. Error Handling & Recovery
  4. Events & Interactive Elements

Part IV — Verification ​

  1. Conformance Suite
  2. Grammar Appendix (prose + PEG fragments)
  3. Glossary
  4. Change Log

Appendices ​

License ​

This specification is released under the MIT License. Implementations are not required to be MIT-licensed.

Acknowledgements ​

This standard is deeply indebted to the CommonMark project for establishing that rigorous prose plus machine-readable test vectors is the right shape for a markdown specification. MdFlow aspires to the same rigor; departures are deliberate, not accidental.