MdFlow

Appearance

16. Change Log ​

All notable changes to the MdFlow Standard are recorded here. This file tracks the specification document, not individual implementations.

The format follows Keep a Changelog conventions, simplified for specifications. Versions follow Semantic Versioning as defined in §1.5.

[1.0.0-draft.2] — 2026-04-16 ​

Added ​

  • Expanded conformance suite to 287 vectors (from 80 in draft.1), clearing the §13.10 minimum of 280. Coverage:
    • Block syntax: 60 vectors (from 18)
    • Inline syntax: 69 vectors (from 19)
    • Custom elements: 40 vectors (from 8)
    • Streaming: 32 vectors (from 9)
    • Errors: 20 vectors (from 5)
    • Security / URL filter: 30 vectors (from 15)
    • Security / attribute filter: 14 vectors (from 5)
    • Security / no raw HTML: 15 vectors (from 6)
    • Extensions / md-plot: 10 vectors (new)
  • md-plot extension specification (src/extensions/md-plot.md) — declarative chart element with constrained content model and hex-color attribute filter.
  • Core adapter for the conformance runner (@mdflow/spec-tests/src/runner/core-adapter.ts) — dynamic-import wrapper around @mdflow/core + bundled plugins so the suite can run against the reference implementation.
  • VitePress sidebar updated to surface md-plot.

Policy ​

  • Q12 locked: spec vectors are the source of truth. When @mdflow/core diverges from a vector, core will be fixed; vectors are not mutated to match implementation.

[1.0.0-draft.1] — 2026-04-15 ​

Added ​

  • Initial public draft of the MdFlow Standard.
  • 16 chapters covering: Introduction, Conformance, Document Model, Lexical Structure, Streaming Model, Block Syntax, Inline Syntax, HTML & Custom Elements, Extension Mechanism, Security Model, Error Handling & Recovery, Events & Interactive Elements, Conformance Suite, Grammar Appendix, Glossary, Change Log.
  • 4 appendices: Reference Implementations, Divergences from CommonMark, Migration Notes, Index of Examples.
  • governance.md — RFC process for post-1.0 changes.
  • Initial PEG grammar fragments in src/grammar/index.peg.
  • Initial conformance vector suite (@mdflow/spec-tests) with vectors under core/ and security/ subtrees.
  • MIT license for the specification text.

Normative decisions locked ​

  • Two conformance classes: Batch and Streaming.
  • Custom-element tags live in extension specifications; the core defines only the safety mechanism.
  • CommonMark-overlap policy: aspire-identical + explicit divergence list (Appendix B).
  • Governance: maintainer team + lightweight RFC via GitHub issue, BDFL acceptance, 14-day minimum discussion window.
  • Vector format: CommonMark-style markdown single source, JSON generated.

Intentional exclusions (deferred or rejected) ​

  • Raw HTML passthrough (rejected — incompatible with the security model).
  • Setext headings (rejected — ATX only for v1.0).
  • Reference-style link definitions (deferred to v1.1).
  • Full numeric HTML entities (rejected — fixed named set only).

Planned ​

[1.1] (tentative) ​

  • Reference-style link definitions ([label]: url title) if round-tripping through the streaming model can be proved sound.
  • Task list items (- [x] done) as a core extension.
  • Footnotes ([^1] + [^1]: definition).
  • Directive fences (:::) lift from reservation to normative.

[2.0] (no timeline) ​

  • Setext headings (if community demand is strong).
  • Full numeric HTML entities, subject to an entity-table spec.
  • Richer attribute grammar for inlines via {...}.

Errata process ​

Errata are not a version bump. They correct clearly-broken vectors or contradictions between prose, grammar, and vectors. Each erratum is filed as a GitHub issue and, once accepted by the BDFL, landed as a patch release (1.0.1) with the erratum listed here.