You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A reference link and its definition do not survive a save. Every reference is rewritten as an inline link carrying a copy of the destination, and the definition block is deleted. A document that names one destination once and points four references at it comes back with four copies and no definition.
Steps to reproduce
Open a document containing a definition and a reference to it:
The definition and the reference form the author wrote are still there. CommonMark's full, collapsed, and shortcut reference forms are all in the supported surface, and corpus/commonmark/links-and-images.md covers each of them.
Actual behavior
Measured against 9626471d by driving the editor mount used by the plugin tests. Stable across a second save:
Document
Saved
[garden report]: /garden "Report" then [Full reference][garden report], [garden report][], and [garden report]
three inline links, each […](/garden "Report"), and no definition line
[leaf]: ../assets/leaf.svg "Leaf" then ![Reference leaf][leaf]

The destination is preserved, so nothing is unreachable, but the shared definition is gone and the file grows a copy per reference.
Documentation, decisions, or prior investigation: corpus/commonmark/links-and-images.md under Full, collapsed, and shortcut reference links and Reference-label normalization; docs/specification.md Supported Markdown.
Done when
A full, collapsed, or shortcut reference link saves in the form it was authored in, with its definition intact.
A reference image does the same.
A definition's title saves in the form it was authored in, on the same rule A link title is rewritten to double quotes on save #261 applies to a
link and an image. A definition writes its title through the same quote option, so the definition handler this issue has to write is the only place that form can be honored.
A reference whose definition is missing keeps behaving as it does today, as literal text rather than a broken link.
Regression coverage asserts the saved form for each reference form.
docs/specification.md records reference links as supported if that is the accepted answer, or records the limitation if it is not.
Notes, logs, screenshots
Diagnosis
The editor schema has no node for a link reference, an image reference, or a definition, so mdast's linkReference, imageReference, and definition nodes are resolved into inline links at parse time and the definitions have nowhere to live. Both forms converge across a second save, so src/features/editor/tests/corpusRoundTrip.test.tsx is green on all of them — the same blind spot #251 records under A green corpus guard does not mean a sub-issue worked.
Implementation direction
This needs schema nodes rather than a serializer override, which makes it the largest of #251's remaining sub-issues and the one most likely to touch product behavior: a reference link has an editing story that an inline link does not, and the definition block needs somewhere to render. Worth agreeing on the intended editing behavior in this issue before implementation, per CONTRIBUTING.md.
Label normalization is a separate question and can be answered later. [Normalized Report] and [normalized report] match one definition today, and the authored casing and spacing of each reference would need preserving for byte identity.
Out of scope
Footnote definitions, which already have a node and survive a save.
The escaping and character-reference differences in the same corpus file, which are filed on their own. The title form of an inline link and an image is A link title is rewritten to double quotes on save #261; only a definition's title is here, because only this issue makes a definition survive to be written.
Summary
A reference link and its definition do not survive a save. Every reference is rewritten as an inline link carrying a copy of the destination, and the definition block is deleted. A document that names one destination once and points four references at it comes back with four copies and no definition.
Steps to reproduce
Open a document containing a definition and a reference to it:
Save it.
Read the file.
Expected behavior
The definition and the reference form the author wrote are still there. CommonMark's full, collapsed, and shortcut reference forms are all in the supported surface, and
corpus/commonmark/links-and-images.mdcovers each of them.Actual behavior
Measured against
9626471dby driving the editor mount used by the plugin tests. Stable across a second save:[garden report]: /garden "Report"then[Full reference][garden report],[garden report][], and[garden report][…](/garden "Report"), and no definition line[leaf]: ../assets/leaf.svg "Leaf"then![Reference leaf][leaf]The destination is preserved, so nothing is unreachable, but the shared definition is gone and the file grows a copy per reference.
Related context
corpus/commonmark/links-and-images.mdunderFull, collapsed, and shortcut reference linksandReference-label normalization;docs/specification.mdSupported Markdown.Done when
link and an image. A definition writes its title through the same
quoteoption, so thedefinitionhandler this issue has to write is the only place that form can be honored.docs/specification.mdrecords reference links as supported if that is the accepted answer, or records the limitation if it is not.Notes, logs, screenshots
Diagnosis
The editor schema has no node for a link reference, an image reference, or a definition, so
mdast'slinkReference,imageReference, anddefinitionnodes are resolved into inline links at parse time and the definitions have nowhere to live. Both forms converge across a second save, sosrc/features/editor/tests/corpusRoundTrip.test.tsxis green on all of them — the same blind spot #251 records underA green corpus guard does not mean a sub-issue worked.Implementation direction
This needs schema nodes rather than a serializer override, which makes it the largest of #251's remaining sub-issues and the one most likely to touch product behavior: a reference link has an editing story that an inline link does not, and the definition block needs somewhere to render. Worth agreeing on the intended editing behavior in this issue before implementation, per
CONTRIBUTING.md.Label normalization is a separate question and can be answered later.
[Normalized Report]and[normalized report]match one definition today, and the authored casing and spacing of each reference would need preserving for byte identity.Out of scope