Improve reference capture

Author: chrisjsewell

markdown_it/port.yaml

@@ -25,7 +25,10 @@
       in favour of using them directly through:
 
         from markdown_it.common.normalize_url import normalizeLinkText
-
+    - |
+      In markdown_it/rules_block/reference.py,
+      record line range in state.env["references"] and add state.env["duplicate_refs"]
+      This is to allow renderers to report on issues regarding references
     - Allow custom renderer to be passed to `MarkdownIt`
     - |
       change render method signatures

markdown_it/rules_block/reference.py

@@ -187,14 +187,24 @@ def reference(state: StateBlock, startLine, _endLine, silent):
     if "references" not in state.env:
         state.env["references"] = {}
 
+    state.line = startLine + lines + 1
+
     if label not in state.env["references"]:
-        # TODO here (as is expected) references that have been previously defined
-        # are ignored. But we should add a record of these (plus line numbers) to the
-        # env, so that renderers may report warnings for these ignored references
-        # rather than 'failing silently'
-        state.env["references"][label] = AttrDict({"title": title, "href": href})
+        state.env["references"][label] = AttrDict(
+            {"title": title, "href": href, "map": [startLine, state.line]}
+        )
+    else:
+        state.env.setdefault("duplicate_refs", []).append(
+            AttrDict(
+                {
+                    "title": title,
+                    "href": href,
+                    "label": label,
+                    "map": [startLine, state.line],
+                }
+            )
+        )
 
     state.parentType = oldParentType
 
-    state.line = startLine + lines + 1
     return True

tests/test_port/test_references.py

@@ -6,15 +6,16 @@
 def test_ref_definitions():
 
     md = MarkdownIt()
-    src = "[a]: abc\n\n[b]: xyz"
+    src = "[a]: abc\n\n[b]: xyz\n\n[b]: ijk"
     env = AttrDict()
     tokens = md.parse(src, env)
     assert tokens == []
     assert env == {
         "references": {
-            "A": {"title": "", "href": "abc"},
-            "B": {"title": "", "href": "xyz"},
-        }
+            "A": {"title": "", "href": "abc", "map": [0, 1]},
+            "B": {"title": "", "href": "xyz", "map": [2, 3]},
+        },
+        "duplicate_refs": [{"href": "ijk", "label": "B", "map": [4, 5], "title": ""}],
     }
 
 
@@ -24,8 +25,8 @@ def test_use_existing_env():
     env = AttrDict(
         {
             "references": {
-                "A": {"title": "", "href": "abc"},
-                "B": {"title": "", "href": "xyz"},
+                "A": {"title": "", "href": "abc", "map": [0, 1]},
+                "B": {"title": "", "href": "xyz", "map": [2, 3]},
             }
         }
     )
@@ -126,8 +127,8 @@ def test_use_existing_env():
     ]
     assert env == {
         "references": {
-            "A": {"title": "", "href": "abc"},
-            "B": {"title": "", "href": "xyz"},
-            "C": {"title": "", "href": "ijk"},
+            "A": {"title": "", "href": "abc", "map": [0, 1]},
+            "B": {"title": "", "href": "xyz", "map": [2, 3]},
+            "C": {"title": "", "href": "ijk", "map": [2, 3]},
         }
     }