Repository navigation
Description
User need
People writing reports, specifications, and research notes need readable citations and reusable link definitions without leaving the visual editor. A document should retain its authored references when it is edited, saved, reopened, or exported.
Current behavior
In 0.5.2, reference-style links remain literal because the block parser disables reference definitions until the inline renderer supports them. Footnote markers and definitions remain visible source in HTML/PDF export, with a warning. DOCX/EPUB use Pandoc's supported native note structures, but that does not provide visual-editor or HTML/PDF support.
See the parser configuration and the export support matrix.
Proposed scope
- Render and edit full, collapsed, and shortcut reference-style links and reference-style images, including optional titles and shared definitions.
- Render footnote references and definitions as readable notes with navigation to the note and back to its reference. Provide an insertion action that avoids identifier collisions.
- Preserve authored identifiers, definition placement, destination spelling, titles, and unrelated source where possible. Editing displayed link text must not silently change a shared destination.
- Keep unresolved or malformed references visible and editable; explain them without discarding source.
- Carry the supported constructs through visual/source/split views, Undo/Redo, save/reopen, and all existing export formats. Preserve the existing saved-revision export contract.
Example document:
Read the [project guide][guide] and the [release notes][].
The result has a supporting note.[^method]
[guide]: https://example.com/guide "Project guide"
[release notes]: https://example.com/releases
[^method]: The measurement uses the documented procedure.Acceptance criteria
- Full, collapsed, and shortcut references resolve consistently, including repeated references and reference-style images.
- Footnotes can be inserted, edited, and navigated using the keyboard; repeated references and missing definitions have defined behavior.
- Editing one paragraph leaves unrelated definitions and authored identifiers intact.
- Source switching, Undo/Redo, save, and reopen preserve meaning and do not lose definitions.
- HTML/PDF include linked notes and resolved references; DOCX/EPUB retain their supported native note/navigation structures. Representative outputs are inspected in their readers.
- Code spans/fences containing reference-like syntax stay literal. Escapes, Unicode labels, titles, duplicate labels, and malformed input have regression coverage.
- User guidance and the export support matrix describe the supported syntax and any remaining limits.
Priority: high for technical and research documents. Related compatibility work: #16, #77, and #85. This request does not set a release target.
Activity