docs: Replace symlinks at build time to use markdown link syntax

docs/conf.py

@@ -21,6 +21,45 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 import os
+import shutil
+from pathlib import Path
+
+
+# -- Preprocessing: Replace symlinks with actual copies ---------------------
+def replace_symlinks_with_copies():
+    """Replace symlinked directories with actual copies at build time (CI only)."""
+    # Only run in CI environments to avoid disrupting local development
+    # GitHub Actions (and most CI systems) set CI=true
+    if not os.environ.get("CI"):
+        print("Skipping symlink replacement (not in CI environment)")
+        return
+
+    docs_dir = Path(__file__).parent
+    symlinks = ["usage-cookbook", "use-case-examples"]
+
+    for symlink_name in symlinks:
+        symlink_path = docs_dir / symlink_name
+
+        # Check if it's a symlink
+        if symlink_path.is_symlink():
+            # Resolve the target
+            target = symlink_path.resolve()
+
+            if target.exists():
+                print(f"Replacing symlink {symlink_name} with actual copy from {target}")
+                # Remove the symlink
+                symlink_path.unlink()
+                # Copy the actual directory
+                shutil.copytree(target, symlink_path)
+            else:
+                print(f"Warning: Symlink target {target} does not exist")
+
+
+# Run preprocessing
+print("Running docs preprocessing...")
+replace_symlinks_with_copies()
+print("Preprocessing complete!")
+
 
 project = "Nemotron"
 copyright = "2026, NVIDIA Corporation"

usage-cookbook/Nemotron-3-Super/README.md

@@ -13,13 +13,13 @@ These notebooks provide end-to-end recipes for deploying and customizing Nemotro
 - **[vllm_cookbook.ipynb](vllm_cookbook.ipynb)** — Deploy Nemotron-3-Super with vLLM.
 - **[sglang_cookbook.ipynb](sglang_cookbook.ipynb)** — Deploy Nemotron-3-Super with SGLang.
 - **[trtllm_cookbook.ipynb](trtllm_cookbook.ipynb)** — Deploy Nemotron-3-Super with TensorRT-LLM.
-- **{doc}`AdvancedDeploymentGuide <AdvancedDeploymentGuide/README>`** — Production deployment configurations for vLLM, SGLang, and TRT-LLM across GPU topologies (GB200, B200, DGX Spark), including MTP speculative decoding, expert parallelism, and tuning guidance.
+- **[AdvancedDeploymentGuide](AdvancedDeploymentGuide/README.md)** — Production deployment configurations for vLLM, SGLang, and TRT-LLM across GPU topologies (GB200, B200, DGX Spark), including MTP speculative decoding, expert parallelism, and tuning guidance.
 
 ### Fine-Tuning
 
-- **{doc}`grpo-dapo <grpo-dapo/README>`** — Full-weight RL training with GRPO/DAPO algorithm, reproducing emergent math reasoning from a base model.
-- **{doc}`lora-text2sql <lora-text2sql/README>`** — Supervised fine-tuning (LoRA) recipe for the Text2SQL use case, including dataset preparation and training with [NeMo Megatron-Bridge](https://github.com/NVIDIA-NeMo/Megatron-Bridge) and [NeMo AutoModel](https://github.com/NVIDIA-NeMo/Automodel) libraries.
+- **[grpo-dapo](grpo-dapo/README.md)** — Full-weight RL training with GRPO/DAPO algorithm, reproducing emergent math reasoning from a base model.
+- **[lora-text2sql](lora-text2sql/README.md)** — Supervised fine-tuning (LoRA) recipe for the Text2SQL use case, including dataset preparation and training with [NeMo Megatron-Bridge](https://github.com/NVIDIA-NeMo/Megatron-Bridge) and [NeMo AutoModel](https://github.com/NVIDIA-NeMo/Automodel) libraries.
 
 ### Agentic
 
-- **{doc}`OpenScaffoldingResources <OpenScaffoldingResources/README>`** — Guides for using Nemotron-3-Super with agentic coding tools (OpenCode, OpenClaw, Kilo Code CLI, OpenHands) via OpenRouter and build.nvidia.com.
+- **[OpenScaffoldingResources](OpenScaffoldingResources/README.md)** — Guides for using Nemotron-3-Super with agentic coding tools (OpenCode, OpenClaw, Kilo Code CLI, OpenHands) via OpenRouter and build.nvidia.com.

usage-cookbook/Nemotron-3-Super/lora-text2sql/README.md

@@ -6,8 +6,8 @@ This directory demonstrates customizing Nemotron-3-Super for the Text2SQL use ca
 
 This directory contains two distinct LoRA fine-tuning tutorials for Text2SQL:
 
-- {doc}`nemo-megatron-bridge <nemo-megatron-bridge/README>` — Recipe using [NeMo Megatron-Bridge](https://github.com/NVIDIA-NeMo/Megatron-Bridge)
-- {doc}`nemo-automodel <nemo-automodel/README>` — Recipe using [NeMo AutoModel](https://github.com/NVIDIA-NeMo/Automodel)
+- [nemo-megatron-bridge](nemo-megatron-bridge/README.md) — Recipe using [NeMo Megatron-Bridge](https://github.com/NVIDIA-NeMo/Megatron-Bridge)
+- [nemo-automodel](nemo-automodel/README.md) — Recipe using [NeMo AutoModel](https://github.com/NVIDIA-NeMo/Automodel)
 
 ## Requirements