MdFlow

Appearance

1. Introduction & Scope ​

1.1 Purpose ​

This document specifies MdFlow v1.0, a standard for parsing and rendering a defined subset of markdown, with two properties that distinguish it from prior markdown specifications:

  1. Streaming-first semantics. Source text arrives as a sequence of chunks of arbitrary size and timing. The specification defines the rendered output at every intermediate point, not only at end-of-input.
  2. Safe custom HTML elements. A bounded class of HTML-like custom elements (md-*) may appear in source text. The specification defines a grammar for which elements and attributes are admissible, and guarantees that admissible source cannot produce unsafe output in a conforming renderer.

1.2 Scope ​

The specification covers:

  • The lexical structure of MdFlow source text.
  • The block-level and inline-level syntactic constructs of MdFlow.
  • The document model — how parsed source is represented as a tree of nodes.
  • The streaming contract — how chunks are processed and how re-renders relate to earlier renders.
  • The custom-element mechanism and its safety guarantees.
  • The plugin mechanism by which third parties may extend the grammar.
  • Error handling and recovery requirements.
  • A conformance test suite and conformance classes.

The specification does not cover:

  • Typography, typographic substitutions (smart quotes, em-dashes, etc.).
  • Internationalization beyond UTF-8 decoding.
  • Bidirectional text, ruby annotation, or East Asian wide-char handling beyond what the DOM provides.
  • User interface concerns of renderers (scrolling, selection, accessibility tree customization beyond the rules in §10 Security Model).
  • Wire formats other than UTF-8 source text.

1.3 Audience ​

This specification is written for implementers: authors of MdFlow parsers, renderers, plugins, and tooling. Prose is terse and uses RFC 2119 keywords (see §2 Conformance). Tutorials, style guides, and authoring advice are not part of the standard; they live in the companion documentation site.

1.4 Relation to CommonMark ​

MdFlow is an independent standard, not a derivative of CommonMark. Where syntactic constructs overlap (e.g., ATX headings, fenced code blocks, emphasis, inline links), MdFlow aspires to produce output byte-identical to a CommonMark-conformant parser, and each relevant clause cites its CommonMark §.

Where MdFlow diverges from CommonMark, the divergence is enumerated in Appendix B — Divergences. Major divergences include:

  • Raw HTML passthrough is not permitted.
  • Setext headings (=== / --- underline form) are not part of v1.0.
  • Reference-style link definitions are not part of v1.0.
  • A formal streaming semantics is specified.
  • md-* custom elements are permitted under a safety grammar.

Implementers MAY publish their MdFlow implementation as also-CommonMark-compliant, provided it passes both test suites; conformance to MdFlow does not entail conformance to CommonMark, and vice versa.

1.5 Versioning ​

MdFlow uses Semantic Versioning for the specification itself:

  • Patch (v1.0.x): clarifications that do not change the set of conforming implementations.
  • Minor (v1.x.0): additions that do not invalidate prior conformance (e.g., new optional syntax, new test vectors that only apply to new features).
  • Major (vx.0.0): breaking changes that may invalidate prior conformance.

Versioning of conformance vectors tracks the specification version.

1.6 Document structure ​

Parts I–IV proceed from foundations to verification. Normative and informative clauses are marked (see §2.1). Every normative clause has at least one corresponding vector in the conformance suite.

1.7 Terminology references ​

Defined terms appear in italics on first load-bearing use and are listed in §15 Glossary. All uses of "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "MAY", "REQUIRED", "RECOMMENDED", and "OPTIONAL" follow RFC 2119; see §2.1.

1.8 Status of this draft ​

v1.0.0-draft.1 (2026-04-15): initial public draft. Feedback via the MdFlow GitHub repository; see Governance for the RFC process.