Skip to content

Support footnotes and reference-style links across editing and export #113

Open

Description

@BinaryOutlook

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions