Skip to content

Reference links are inlined and their definitions deleted on save #260

Description

@Azganoth

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

  1. Open a document containing a definition and a reference to it:

    [garden report]: /garden "Report"
    
    [Full reference][garden report]
  2. Save it.

  3. 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.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] ![Reference leaf](../assets/leaf.svg "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

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.

Metadata

Metadata

Assignees

Labels

BugSomething isn't working

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions