docs/editor-behavior/markdown-standards.md
This is the master standards file for Plate's markdown-first editing work.
It exists to stop two common failure modes:
This file records the methodology and authority model after the current reference pass. It exists so later behavior work does not drift back into guesswork.
Define the standards process for Plate's markdown-first profile so we can:
Typora is a high-signal reference pool for many markdown-first surfaces.
It is not a governing default owner for every markdown-native row.
Use it for:
Obsidian is a high-signal reference pool for dual-mode and note-linked-navigation surfaces.
Use it for:
Do not treat Obsidian as a broad default owner for:
Notion is a high-signal reference pool for many block-editor-native elements.
Use it for:
Google Docs is a high-signal reference pool for document-style editing.
Use it for:
GitHub is a high-signal product reference for GFM-only syntax and rendered semantics.
Use it for:
Do not use GitHub as the main WYSIWYG editing authority for generic text behavior. Those surfaces usually point toward Typora for markdown-native editing and Google Docs for table-feel and document-feel, but the concrete row still has to choose its own authority.
Milkdown is the inspectable open-source cross-check.
Use it to inspect:
Use this order when deciding Plate behavior.
Every current feature family in the readable spec, parity matrix, and protocol docs must state:
block non-voidblock void atominline non-void spaninline void atomleaf marktext tokenoverlay / no nodedirectionalhardoutwardnone / n-aRules:
contentEditable={false}Do not treat this section as governing law.
Use it to route a pass toward likely sources. Concrete sections and protocol rows still choose authority explicitly.
[text](url) automd and math delimiter triggers belong with
source-preserving conversion behavior, not with plain mark or
text-substitution autoformatFor parse and serialize semantics, prefer the syntax spec first:
Pick the strongest reference for the concrete surface you are actually specifying, not for the broad family label wrapped around it.
Family labels are routing hints only.
Examples:
That is normal. Do not force one owner across the whole family unless the evidence genuinely supports it.
Use Milkdown as the open-source companion reference for inspectable markdown behavior and engine-level cross-checking.
If the specs are silent or the references disagree, first look for the strongest adjacent mainstream precedent instead of inheriting legacy Plate behavior.
Only when that still fails should Plate choose explicitly and record that choice in the spec and tests.
Do not let a category label decide the winner.
Each concrete surface, family split, or protocol row should choose the strongest authority it can actually justify.
Default to that behavior unless it directly conflicts with syntax correctness or Plate's document model.
Document:
Only then make an explicit fallback decision. Do not smuggle it in as if it were a standard.
Do not treat current behavior as a tie-breaker. Existing behavior is evidence, not authority.
This standards lane covers:
It does not claim that every Plate block is native markdown. It does claim that every existing content-affecting feature should have an explicit authority and coverage status.
During this major, defer minor new-feature work in the markdown lane unless it is required to unlock parity, cleanup, or profile architecture.
Spend the major budget on:
Treat streaming as regression coverage for this major, not as a proactive work queue, unless an active current-feature change breaks it.
Do not dilute the release with "nice to have" syntax or extension work while core existing behavior is still inconsistent.
Use the same taxonomy across docs and tests.
Examples:
Examples:
Examples:
Examples:
These still need explicit behavior decisions:
Every meaningful rule must have a stable spec ID.
Examples:
EDIT-BQ-ENTER-EMPTY-001EDIT-LIST-BACKSPACE-START-002PARITY-GFM-TASKLIST-001PARITY-MATH-BLOCK-003STREAM-BQ-PARTIAL-001EDIT editing behaviorPARITY parse/serialize/round-trip paritySTREAM streaming or incremental markdown behaviorDEV intentional Plate deviationThe end goal is TDD from these docs.
Every locked rule should map to:
Test names should reference spec IDs directly when the behavior is important enough to survive refactors.
Use these labels in the spec docs and parity matrix:
draft pre-reference framingaudit reference research in progressproposed likely decision, not lockedlocked accepted target behaviordeviation intentionally different from the referenceDeviations are allowed. Hidden deviations are not.
When Plate differs from Typora, Obsidian, Google Docs, Notion, or Milkdown, record:
Good reasons:
Bad reasons:
This is the order for the later audit.
proposed to locked.When auditing a rule, always capture:
Without that, the audit will drift into vague prose.
Do not rerun the broad markdown-first reference audit by default.
Use the live command pack and roadmap first:
Rerun research or audit only when: