Support footnotes and reference-style links

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Added
+
+- Reference links and images, plus editable footnotes with insertion, keyboard navigation, and export support. See [syntax and limits](docs/editor-guide.md#reference-links-and-footnotes) ([#113](https://github.com/BinaryOutlook/binary-markdown/issues/113)).
+
 ## 0.5.2
 
 A compatible update following 0.5.1. It keeps unsaved edits when another program writes the open file, groups settings into categories, and adds optional icon-only code-block buttons. See the [0.5.2 notes](release-notes/0.5.2.md) for what changes after updating and its known limitations. [GitHub Releases](https://github.com/BinaryOutlook/binary-markdown/releases) identifies published packages and their validation.

docs/editor-guide.md

@@ -36,7 +36,7 @@ Code spans, code blocks, equations, and generated document blocks cannot be unde
 
 ## Insert menu
 
-The Insert workspace remains available in both **Full** and **Simple** mode. Open the three-dot **More toolbar actions** menu, search for **Insert**, and choose the **Insert** command. The workspace includes inline equations, block equations, tables, code blocks, links, images, Mermaid diagrams, and a managed table of contents. Search the three-dot menu for an individual insertion command to run it directly, or use its existing toolbar button, shortcut, or Action Palette entry.
+The Insert workspace remains available in both **Full** and **Simple** mode. Open the three-dot **More toolbar actions** menu, search for **Insert**, and choose the **Insert** command. The workspace includes inline equations, block equations, tables, code blocks, links, images, footnotes, Mermaid diagrams, and a managed table of contents. Search the three-dot menu for an individual insertion command to run it directly, or use its existing toolbar button, shortcut, or Action Palette entry.
 
 Opening the menu retains your caret or selection. Use up/down arrows or `Home`/`End` to navigate, `Enter` or `Space` to choose an item, and `Escape` to close it. Opening, navigating, or cancelling the menu does not edit the document. Cancelling a link or image dialog also leaves the document and undo history unchanged. Confirmed insertions use the retained location and can be undone in one step.
 
@@ -83,6 +83,27 @@ Search the Insert workspace or choose **All**, **Structure**, **Equations**, **C
 
 ---
 
+## Reference links and footnotes
+
+Full (`[text][guide]`), collapsed (`[guide][]`), and shortcut (`[guide]`) references, including images, share definitions and optional titles. Open **Link definition […] — Edit definition** to change a shared destination or title. Editing link text keeps its target, expanding collapsed or shortcut syntax when needed.
+
+```markdown
+Read the [project guide][guide] and [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 follows the documented procedure.
+```
+
+Choose **Footnote** from Insert or the Action Palette to add a marker at the caret, or after selected text. The editor creates an unused `note-N` definition at the end and selects its text. Repeated references share a number and have separate return links; use `Tab`, then `Enter` or `Space`, to navigate.
+
+Open **Footnote … — Edit definition** to edit note Markdown; indent continuation blocks by four spaces. Press `Ctrl/Cmd+Enter` or leave the field to refresh its preview. Save and Undo work in the field. Visual, Source, and Split share definitions; Split's preview is read-only.
+
+Labels ignore case; link labels also normalize whitespace. Footnote labels cannot be empty or contain whitespace or square brackets. The first definition wins; duplicates and unresolved full/collapsed links or notes show explanations. Unresolved and malformed syntax stays editable. Code and escaped markers stay literal.
+
+Unchanged blocks preserve source spelling, identifiers, and definition placement; edited blocks may normalize formatting. HTML/PDF keep notes at their definition locations, not page bottoms. DOCX/EPUB use native notes and may number repeats separately. Unused and duplicate notes stay in source but are omitted from exports. See [export support](export-subsystem.md#rendering-and-format-support).
+
 <a id="-special-operations"></a>
 
 ## Keyboard operations

docs/export-subsystem.md

@@ -70,7 +70,10 @@ The [fixed fixtures](../test/fixtures/exports/README.md) exercise the following
 | Images and fonts | Resolve and embed needed assets; standalone HTML works after relocation offline. | Package compatible media; preserve source resolution without deliberate downsampling. |
 | Raw HTML, editor extensions, unsupported constructs | Follow declared renderer support and remove editor-only machinery. | Explicit target-specific behavior; visible fallback/warning for known incompatible content. |
 | Front matter, TOC, internal image directives | Exclude front matter/editor-only directives from visible content. Save expands `[TOC]` markers and refreshes managed contents. Exports require current TOCs and include links to unique heading destinations without editor controls or boundary comments. | Normalize temporary input deliberately; avoid duplicate TOCs or leaked directives. |
-| Footnotes | Existing footnote markers/definitions remain visible source with a warning; linked footnotes are not generated. | Use Pandoc's supported native note/navigation structures, with target-specific verification. |
+| Reference-style links and images | Full, collapsed, and shortcut references resolve shared definitions and titles; unresolved source stays visible. | Pandoc resolves references and packages supported images. |
+| Footnotes | Numbered links and return links at definition locations, not page bottoms. Unresolved/malformed notes stay visible with warnings. | Native notes/navigation; repeated references may receive separate numbers. |
+
+The first definition wins. Unused/duplicate notes stay in source but are omitted from output. See [syntax and source preservation](editor-guide.md#reference-links-and-footnotes). The saved-revision requirement still applies.
 
 Do not claim a parser capability merely because Pandoc can write its output format. Existing rendering bugs are not silently expanded into export guarantees. Declare known limitations and preserve supported content; fallback acceptance is not permission to hide a regression by downgrading the support matrix.
 

media/export-help.md

@@ -108,9 +108,10 @@ The anchored Export panel keeps format availability, setup actions, and job stat
 
 ## Initial format limitations
 
-- HTML and PDF reuse supported editor rendering. HTML retains the editor theme; PDF uses the white/theme setting above. Inline `$...$` / `\(...\)`, display `$$...$$` / `\[...\]`, and fenced `math` blocks render with KaTeX. Backslash recognition follows `binary-markdown.math.backslashDelimiters` (enabled by default). Saved tables of contents render as links to headings. Footnotes remain visible source with warnings. Invalid supported math/diagrams receive source fallbacks.
+- HTML and PDF reuse supported editor rendering. HTML retains the editor theme; PDF uses the white/theme setting above. Inline `$...$` / `\(...\)`, display `$$...$$` / `\[...\]`, and fenced `math` blocks render with KaTeX. Backslash recognition follows `binary-markdown.math.backslashDelimiters` (enabled by default). Saved tables of contents render as links to headings. Invalid supported math/diagrams receive source fallbacks.
 - PDF uses simple pagination. Generous blank areas are acceptable; oversized text and tables split, while graphics scale to fit.
 - DOCX and EPUB prioritize editable structure and native math. Enabled backslash equation delimiters are converted to dollars in an export-only copy held in memory; the source file is preserved, and temporary conversion files are removed when the job ends. TeX command support and layout can differ from KaTeX. Raw HTML is exported as readable source when its behavior cannot be preserved.
+- Reference links/images resolve shared definitions and titles. HTML/PDF notes have numbered links and return links at definition locations, not page bottoms; unresolved/malformed notes stay visible with warnings. DOCX/EPUB use native notes and may number repeats separately. The first definition wins; unused/duplicate notes stay in source but are omitted from output.
 - DOCX code blocks have a pale background and, when unnumbered, a border. DOCX and direct PDF exports can show the declared language (for example, `python`) in a small italic tab at the selected corner. The outline faces the adjoining code edge and uses a matching background and border. Blocks without a language do not receive a guessed label. DOCX code remains editable, with syntax coloring for languages Pandoc recognizes; PDF retains its browser-rendered code formatting.
 - Supported images retain source resolution. Unsupported image formats, unreadable resources and unrepresentable diagrams receive visible fallbacks.
 - Only needed referenced resources may be fetched. Conversion remains local. Standalone HTML embeds supported resources for offline viewing.

package.json

@@ -607,6 +607,7 @@
     "@xmldom/xmldom": "0.9.12",
     "katex": "0.18.2",
     "markdown-it": "14.3.3",
+    "markdown-it-footnote": "4.0.0",
     "mermaid": "10.9.8",
     "turndown": "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2"

reports/README.md

@@ -23,6 +23,7 @@ These records preserve observations about particular revisions and environments.
 
 | Recorded scope | Report | Evidence boundary |
 | --- | --- | --- |
+| 2026-11-14 footnotes and reference links | [Issue #113 acceptance audit](validation/2026-11-14-footnotes-references.md) | Local implementation, parser/browser regressions, four-format export inspection, and remaining installed-host acceptance |
 | 2026-10-07 0.5.0 readiness | [Integrated scope, candidate acceptance and validation follow-up](validation/2026-10-07-0.5.0-readiness.md) | Exact inspected main baseline, accepted RC2, dependency and diagnostic fixes, candidate boundaries and remaining release gates |
 | 2026-10-02 scoped AI visual fidelity | [Review summary and archived evidence](validation/2026-10-02-ui-ux-visual-fidelity/report.md) | Assessed source, 82 required cases, verdict boundaries, archive checksums and links to complete retained evidence; owner acceptance remains separate |
 | 2026-10-01 selected UI/UX implementation | [Selected designs, screenshots, and security audit](validation/2026-10-01-selected-ui-ux/report.md) | All 12 selected directions, synthetic browser visuals, local regression results, scoped security review, and pending maintainer acceptance |

reports/validation/2026-11-14-footnotes-references.md

@@ -0,0 +1,56 @@
+# Footnotes and reference links: issue #113 validation
+
+Reviewed on 2026-11-14 (Asia/Singapore), before publication. [Issue #113](https://github.com/BinaryOutlook/binary-markdown/issues/113) was implemented on `feat/footnotes-reference-links` from remote `main` at `7982568add8140bcfa2edef7bd3af2b6fed122c1`. The [receipt](evidence/2026-11-14-footnotes-references.json) records changed runtime inputs, tool versions, and output hashes. Artifacts remain in the ignored local `validation-evidence/issue-113/` directory. This is development validation, not release acceptance.
+
+## Acceptance checklist
+
+| Criterion | Result |
+| --- | --- |
+| Reference forms and images | Full, collapsed, shortcut, repeated, and image references resolve shared definitions and titles. Parser and browser tests cover edits and linked images. |
+| Footnote editing and navigation | Insertion avoids identifier collisions. Definition editing, keyboard navigation, repeated references, missing definitions, and unused/duplicate preview navigation pass. |
+| Source preservation | Adjacent edits preserve unrelated definitions, placement, identifiers, destinations, and titles. Link text edits retain the shared target. |
+| Views, history, save/reopen | Visual/Source/Split, Undo/Redo, save acknowledgments, and reload pass in the production browser harness. Installed-VS-Code persistence remains unverified. |
+| Export and readers | HTML/PDF links and native DOCX/EPUB notes pass converter and reader checks below. Native tests also verify image bytes and unchanged source. |
+| Syntax edge cases | Code, escapes, Unicode, titles, duplicates, malformed definitions, nested images, and reference-like math have regression coverage. |
+| Documentation | The editor guide, support matrix, packaged help, and changelog describe syntax and limits. Source and rendered documentation were reviewed. |
+
+## Verification
+
+| Check | Result |
+| --- | --- |
+| Compilation and production fixtures | Passed; Node 24.21.0 |
+| Complete unit suite | 475 passed, 20 optional checks skipped, 0 failed |
+| TypeScript lint | 0 errors; 11 warnings in unchanged files |
+| Full browser run | 1,275 passed, 1 stale command-count assertion failed |
+| Final affected browser run | 149 passed, 0 failed, retries disabled |
+| Real Pandoc reference/footnote test | 1 passed; Pandoc 3.8.3 produced DOCX and EPUB |
+| Dependency audit | 0 vulnerabilities |
+| Documentation and whitespace | Passed |
+
+The command-count assertion was corrected for the new Footnote action. The final affected run covers that fix, reference/footnote behavior, insertion, exports, and selected UI checks, including new Split and unused-note navigation regressions. The full suite was not repeated after those corrections.
+
+The installed Chromium sandbox helper could not initialize. Browser checks used a temporary local configuration with Chromium's inner sandbox disabled; repository and CI settings were unchanged. Optional converter/package checks were skipped in the ordinary unit run; the explicit Pandoc test ran separately.
+
+## Output inspection
+
+A synthetic document combined shared links, repeated case-varied notes, a table, a quotation, literal code, multi-paragraph notes, and math.
+
+- **HTML:** Chromium displayed resolved links and readable notes without editor controls.
+- **PDF:** Rasterized output was visually inspected. All six note/return links resolved; the document also contained six external links.
+- **DOCX:** Headless LibreOffice rendered readable page-bottom notes, formatting, links, and math. Repeated references received separate numbers. Interactive Word editing was not tested.
+- **EPUB:** EPUB.js displayed the exported book, three native note references, and their bodies. Forward and return navigation worked.
+
+HTML/PDF retain notes at authored locations and share repeated-reference numbers; DOCX/EPUB may repeat native notes. These observations do not establish identical behavior across readers or platforms.
+
+## Reproduction and remaining acceptance
+
+Use the repository root, `.node-version`, and the [testing](../../docs/testing/README.md) and [export verification](../../docs/export-verification.md) guides. The feature-specific checks are:
+
+```sh
+CI=1 npx playwright test test/specs/references-footnotes.spec.ts --workers=2 --retries=0
+EXPORT_REAL_TOOLS=1 node --test --test-name-pattern='real Pandoc preserves reference links' test/unit/export-backends.test.js
+```
+
+Compile and regenerate fixtures first. Set `EXPORT_PANDOC_PATH` if Pandoc is outside tool discovery; the commands use the normal browser configuration.
+
+Remaining acceptance: install a fresh development VSIX in an isolated VS Code profile, edit references and notes in Visual/Source/Split, then save, close, reopen, and compare source while exercising Undo/Redo. Interactive Word editing and save/reopen remain unverified. This report does not close the issue.

reports/validation/evidence/2026-11-14-footnotes-references.json

@@ -0,0 +1,56 @@
+{
+  "reviewDate": "2026-11-14",
+  "timezone": "Asia/Singapore",
+  "issue": 113,
+  "baseCommit": "7982568add8140bcfa2edef7bd3af2b6fed122c1",
+  "sourceState": "Uncommitted development changes on feat/footnotes-reference-links",
+  "changedRuntimeInputsSha256": {
+    "package-lock.json": "d3821188e3b2096b331f167f3f94ef97630334b42d8df3656ebc44edf3b5584c",
+    "package.json": "a93785b289e995fd1d7808eb5d56aa6a882e539cf3b82acec98069b01675e638",
+    "src/i18n/locales/en.ts": "be30010cf9add5982a4181d55ca5d852991bef89b158428d187e2b093b93f3ef",
+    "src/i18n/locales/es.ts": "7f9f61be9b3b96e9f51734dabf2407999c1dcbf44aa912bba475ec2c7c1d4f10",
+    "src/i18n/locales/fr.ts": "ebd81847c3c8f508e9f0669b6fb02d9cff0cfc1ab9708fb857db5d454ef53795",
+    "src/i18n/locales/ja.ts": "fd1033c09bf4a8a8e5bfc890c09a7e789f59160b5bbc357655c3bcaf08f9c193",
+    "src/i18n/locales/ko.ts": "bdec4b3b5bf93eca562bce372d37a9e805d4742b85ba02e1b37dac1ebf7206bb",
+    "src/i18n/locales/zh-cn.ts": "8faab73a5420526c087b02b12d22df94a4751821ed5d2f4fa407bbadaf162a38",
+    "src/i18n/locales/zh-tw.ts": "697d4d44bd6daa619d83c2949289ed0bf7f96e276430155f998c30cca0e63600",
+    "src/shared/markdown-blocks.js": "7b5b22a49f31a1b0e0fea890870f6979defd64cba736570808e240ccb6ab0c8a",
+    "src/shared/markdown-references.js": "660db80896ccb67fec766a68fa69a9f71bd3d907888b42248734471a96b22e55",
+    "src/webview/editor.js": "e991a36b6be97b20ef4a4ea9be3467ce97909a8576dfb1d50dcfc73e9e6f08cf",
+    "src/webview/editor/blocks/export.js": "4849125c267067aaab0eace7048f18fee8c3a9d971d1705ec66bb8eb340968ea",
+    "src/webview/editor/blocks/references.js": "57e8e35e1365d9eccaf35c2a11bd443b5198e72e3efd211ca5fb99d006391ddb",
+    "src/webview/editor/blocks/render.js": "95c804bedff36c03cdf80b0db5b428284ed72faab29594344f75fd44f9655ece",
+    "src/webview/editor/blocks/special.js": "60155da84d34b891903dc006ca1ec17958d1a3dd74a028f669113382ba33f879",
+    "src/webview/editor/codec/blocks.js": "09017a2a7b290fdbbe250b388f2dbccc94f15b18ca8dea4b055edab227cd687d",
+    "src/webview/editor/codec/inline.js": "c659a06ca18d978b2312f7c8063756ab5a4fa03a65b2e60db74ca1522e623649",
+    "src/webview/editor/codec/references.js": "e8e9dde8e2cd9589629e350d3269aa0d364511f4447161a0072a5e83ae499d17",
+    "src/webview/editor/input/dispatch.js": "973640d48542f99d2db6d7e23aa0fb21acddfbfe012d7af52faaba80e0206e60",
+    "src/webview/editor/transfer/clipboard.js": "736ae9ea03599137849c047b6d1c7c96a90f7f2afbae49e7151b7a8b17392483",
+    "src/webview/editor/transfer/paste.js": "24ef9fb2888e5b476fe418ac9a7a62698f30bb1d7ea4151e3f789d4a05abdce9",
+    "src/webview/editor/ui/commands.js": "5e7d2f95b0f3639d08eff680cedd61e7efdfc6c4c78f6763351e3bfbae46121c",
+    "src/webview/editor/ui/menus.js": "4346fde5d9dded8b4575a63342a003ce74bad13ac45fc8157ba83b080a02eb70",
+    "src/webview/styles.css": "4b684910c37725f217ba55291be8ae606b308731e24520023fb5b3286b9628b9"
+  },
+  "artifactSha256": {
+    "review.md": "b381a6acfc605c7fde9efd3998b2c986911b9fc6afaed3096a956fa5fced46b0",
+    "review.html": "222cdc0d2712e455e1a069311a7bcc1a2b713f998f7c8cde1bc8bd42229d8f7a",
+    "review.pdf": "3b0cd33ffd31f2c2a10112164137d4cf326be45b0d4b9b7f208aadc748b7369b",
+    "review.docx": "c506d215818828d1c4f1e23ef2ffd1faf6419a7918564e54733a8b5b5251c202",
+    "review.epub": "dfec1ab79666a558f819440a9740a8930097665131eb1e53edd412bcb16e97bf",
+    "docx-reader/review.pdf": "d9d2fd019805d55d5c6910f7076ed1bf71f3c8749f23042216e034272b429190"
+  },
+  "pdfLinkInspection": {
+    "pages": 1,
+    "namedNoteLinks": 6,
+    "externalLinks": 6,
+    "allNamedLinksResolve": true
+  },
+  "tools": {
+    "node": "24.21.0",
+    "chromium": "154.0.8037.57",
+    "pandoc": "3.8.3",
+    "docxReader": "LibreOfficeDev 26.8.0.0.alpha0 (headless PDF rendering)",
+    "epubReader": "EPUB.js 0.3.93 in Chromium",
+    "pdfInspection": "PyMuPDF 1.26.6; Poppler rasterization"
+  }
+}