feat(docs): Support cross language "auto links" (#5699)

Introduces a syntax for cross-reference links that work across language
and change behavior depending on which scope they appear in.


```markdown
@[interrupt]

:::python
@[StateGraph]
:::

:::js
@[create_react_agent]
:::

```

Can be compiled to

```markdown

# a link that changes based on global context or compile target
<div> ... </div>  -> `interrupt` in global context

:::python
[StateGraph](link to python cross reference)
:::

:::js
[create_react_agent](link to js cross reference)
:::
```



TODO:

- [x] fix broken unit test
- [x] no f strings in logger (it's a sin)
- [x] remove cross-refs.txt (we'll instead start updating the cross link
map)

docs/_scripts/handle_auto_links.py

@@ -0,0 +1,156 @@
+"""Logic to identify and transform cross-reference links in markdown files.
+
+This module allows supporting custom markdown syntax for "autolinks". These are links
+that will be transformed based on the current scope context, such as "global", "python",
+or "js" into an appropriate markdown link format.
+
+For example,
+
+```markdown
+@[StateGraph]
+```
+
+May be transformed into:
+
+```markdown
+[StateGraph](some_path/api-reference/state-graph.md)
+```
+
+The transformation value depends on the scope in which the link is used.
+"""
+
+import logging
+import re
+
+from _scripts.link_map import SCOPE_LINK_MAPS
+
+logger = logging.getLogger(__name__)
+
+
+def _transform_link(
+    link_name: str, scope: str, file_path: str, line_number: int
+) -> str | None:
+    """Transform a cross-reference link based on the current scope.
+
+    Args:
+        link_name: The name of the link to transform (e.g., "StateGraph").
+        scope: The current scope context ("global", "python", "js", etc.).
+        file_path: The file path for error reporting.
+        line_number: The line number for error reporting.
+
+    Returns:
+        A formatted markdown link if the link is found in the scope mapping,
+        None otherwise.
+
+    Example:
+        >>> _transform_link("StateGraph", "python", "file.md", 5)
+        "[StateGraph](https://langchain-ai.github.io/langgraph/reference/graphs/#langgraph.graph.StateGraph)"
+
+        >>> _transform_link("unknown-link", "python", "file.md", 5)
+        None
+    """
+    if scope == "global":
+        # Special scope that is composed of both Python and JS links
+        # For now, we will substitute in the python scope!
+        # But we need to add support for handling both scopes.
+        scope = "python"
+        logger.error(
+            "Encountered unhandled 'global' scope. Defaulting to 'python'."
+            "In file: %s, line %d, link_name: %s",
+            file_path,
+            line_number,
+            link_name,
+        )
+    link_map = SCOPE_LINK_MAPS.get(scope, {})
+    url = link_map.get(link_name)
+
+    if url:
+        return f"[{link_name}]({url})"
+    else:
+        # Log error with file location information
+        logger.info(
+            # Using %s
+            "Link '%s' not found in scope '%s'. "
+            "In file: %s, line %d. Available links in scope: %s",
+            link_name,
+            scope,
+            file_path,
+            line_number,
+            list(link_map.keys() if link_map else []),
+        )
+        return None
+
+
+CONDITIONAL_FENCE_PATTERN = re.compile(
+    r"""
+    ^                       # Start of line
+    (?P<indent>[ \t]*)      # Optional indentation (spaces or tabs)
+    :::                     # Literal fence marker
+    (?P<language>\w+)?      # Optional language identifier (named group: language)
+    \s*                     # Optional trailing whitespace
+    $                       # End of line
+    """,
+    re.VERBOSE,
+)
+CROSS_REFERENCE_PATTERN = re.compile(
+    r"""
+    @                       # Literal @ symbol
+    \[                      # Opening bracket
+    (?P<link_name>[^\]]+)   # Link name - one or more non-bracket characters
+    \]                      # Closing bracket
+    """,
+    re.VERBOSE,
+)
+
+
+def _replace_autolinks(markdown: str, file_path: str) -> str:
+    """Preprocess markdown lines to handle @[links] with conditional fence scopes.
+
+    This function processes markdown content to transform @[link_name] references
+    based on the current conditional fence scope. Conditional fences use the
+    syntax :::language to define scope boundaries.
+
+    Args:
+        markdown: The markdown content to process.
+        file_path: The file path for error reporting.
+
+    Returns:
+        Processed markdown content with @[references] transformed to proper
+        markdown links or left unchanged if not found.
+
+    Example:
+        Input:
+            "@[StateGraph]\\n:::python\\n@[Command]\\n:::\\n"
+        Output:
+            "[StateGraph](url)\\n:::python\\n[Command](url)\\n:::\\n"
+    """
+    # Track the current scope context
+    current_scope = "global"
+    lines = markdown.splitlines(keepends=True)
+    processed_lines = []
+
+    for line_number, line in enumerate(lines, 1):
+        line_stripped = line.strip()
+
+        # Check if this line defines a new conditional fence scope
+        fence_match = CONDITIONAL_FENCE_PATTERN.match(line_stripped)
+        if fence_match:
+            language = fence_match.group("language")
+            # Set scope to the specified language, or reset to global if no language
+            current_scope = language.lower() if language else "global"
+            processed_lines.append(line)
+            continue
+
+        # Transform all @[link_name] references in this line based on current scope
+        def replace_cross_reference(match: re.Match[str]) -> str:
+            """Replace a single @[link_name] with the scoped equivalent."""
+            link_name = match.group("link_name")
+            transformed = _transform_link(
+                link_name, current_scope, file_path, line_number
+            )
+            return transformed if transformed is not None else match.group(0)
+
+        transformed_line = CROSS_REFERENCE_PATTERN.sub(replace_cross_reference, line)
+        processed_lines.append(transformed_line)
+
+    return "".join(processed_lines)