From c1343601d93e1dbd7e9d43f773a9e7a95ce089eb Mon Sep 17 00:00:00 2001
From: Eugene Yurtsev <eyurtsev@gmail.com>
Date: Mon, 16 Jun 2025 12:58:20 -0400
Subject: [PATCH] x

---
 docs/_scripts/link_map.py       |  3 +++
 docs/_scripts/notebook_hooks.py | 38 +++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)
 create mode 100644 docs/_scripts/link_map.py

diff --git a/docs/_scripts/link_map.py b/docs/_scripts/link_map.py
new file mode 100644
index 000000000..6bac5950a
--- /dev/null
+++ b/docs/_scripts/link_map.py
@@ -0,0 +1,3 @@
+JS_LINK_MAP = {
+    "langgraph.types.interrupt": "https://langchain-ai.github.io/langgraphjs/reference/functions/langgraph.interrupt-2.html",
+}
diff --git a/docs/_scripts/notebook_hooks.py b/docs/_scripts/notebook_hooks.py
index a50b12e62..3071c68c7 100644
--- a/docs/_scripts/notebook_hooks.py
+++ b/docs/_scripts/notebook_hooks.py
@@ -16,6 +16,7 @@ from mkdocs.structure.pages import Page
 
 from _scripts.generate_api_reference_links import update_markdown_with_imports
 from _scripts.notebook_convert import convert_notebook
+from _scripts.link_map import JS_LINK_MAP
 
 logger = logging.getLogger(__name__)
 logging.basicConfig()
@@ -158,6 +159,33 @@ def _add_path_to_code_blocks(markdown: str, page: Page) -> str:
     return code_block_pattern.sub(replace_code_block_header, markdown)
 
 
+def _resolve_cross_references(md_text: str, link_map: dict[str, str]) -> str:
+    """Replace [title][identifier] with [title](url) using language-specific link_map.
+
+    Args:
+        md_text: The markdown text to process.
+        link_map: mapping of identifier to URL.
+
+    Returns:
+        The processed markdown text with cross-references resolved.
+    """
+    # Pattern to match [title][identifier]
+    pattern = re.compile(r"\[([^\]]+)\]\[([^\]]+)\]")
+
+    def replace_reference(match: re.Match) -> str:
+        """Replace the matched reference with the corresponding URL."""
+        title, identifier = match.group(1), match.group(2)
+        url = link_map.get(identifier)
+
+        if url:
+            return f"[{title}]({url})"
+        else:
+            # Leave it unchanged if not found
+            return match.group(0)
+
+    return pattern.sub(replace_reference, md_text)
+
+
 def _apply_conditional_rendering(md_text: str, target_language: str) -> str:
     if target_language not in {"python", "js"}:
         raise ValueError("target_language must be 'python' or 'js'")
@@ -289,6 +317,16 @@ def _on_page_markdown_with_config(
     # Apply conditional rendering for code blocks
     target_language = kwargs.get("target_language", "js")
     markdown = _apply_conditional_rendering(markdown, target_language)
+    if target_language == "js":
+        markdown = _resolve_cross_references(markdown, JS_LINK_MAP)
+    elif target_language == "python":
+        # Via a dedicated plugin
+        pass
+    else:
+        raise ValueError(
+            f"Unsupported target language: {target_language}. "
+            "Supported languages are 'python' and 'js'."
+        )
 
     # Add file path as an attribute to code blocks that are executable.
     # This file path is used to associate fixtures with the executable code