docs: Add conditional js/python rendering (#5128)

# Overview

Adding conditional rendering logic to co-locate js and python documentation.

* `:::` conditional syntax can be used to switch between python only or js only content.
* Contains simple unit tests for `:::`
* PR adds set up for a way to implement a context switch between languages, but it will not be enabled until JS content is merged in.
* Contains a script that can add javascript documentation 

Implementation of: https://github.com/langchain-ai/langgraph/pull/5118

## Example

Example of conditional rendering / compilation.


```markdown

### Config (static context)

Config is for immutable data like user metadata or API keys. Use
when you have values that don't change mid-run.

Specify configuration using a key called **"configurable"** which is reserved
for this purpose:


:::python

This content will only be rendered for the python site.
:::

:::js
this content will only be rendered for the js / ts site.
:::

```

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,62 @@ 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'")
+
+    pattern = re.compile(
+        r"(?P<indent>[ \t]*):::(?P<language>\w+)\s*\n"
+        r"(?P<content>((?:.*\n)*?))"  # Capture the content inside the block
+        r"(?P=indent):::"  # Match closing with the same indentation
+    )
+
+    def replace_conditional_blocks(match: re.Match) -> str:
+        """Keep active conditionals."""
+        language = match.group("language")
+        content = match.group("content")
+
+        if language not in {"python", "js"}:
+            # If the language is not supported, return the original block
+            return match.group(0)
+
+        if language == target_language:
+            return content
+
+        # If the language does not match, return an empty string
+        return ""
+
+    processed = pattern.sub(replace_conditional_blocks, md_text)
+    return processed
+
+
 def _highlight_code_blocks(markdown: str) -> str:
     """Find code blocks with highlight comments and add hl_lines attribute.
 
@@ -257,6 +314,20 @@ def _on_page_markdown_with_config(
     # Apply highlight comments to code blocks
     markdown = _highlight_code_blocks(markdown)
 
+    # Apply conditional rendering for code blocks
+    target_language = kwargs.get("target_language", "python")
+    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
     # which can be used in CI to test the docs without making network requests.