diff --git a/docs/observability-plugin/about.mdx b/docs/observability-plugin/about.mdx
index fe3fe601..5e3eeef8 100644
--- a/docs/observability-plugin/about.mdx
+++ b/docs/observability-plugin/about.mdx
@@ -64,7 +64,7 @@ guardrails before exporters receive sensitive payloads.
 
 For trace incidents involving missing traces, wrong scope attachment, export
 failures, duplicate events, or sensitive telemetry, use the
-[Trace Incident Runbook](../../troubleshooting/trace-incident-runbook.md).
+[Trace Incident Runbook](/resources/troubleshooting/trace-incident-runbook).
 
 ## Correlating Trajectories And Traces
 
diff --git a/docs/resources/support-and-faqs.mdx b/docs/resources/support-and-faqs.mdx
index 4beb3987..7836611b 100644
--- a/docs/resources/support-and-faqs.mdx
+++ b/docs/resources/support-and-faqs.mdx
@@ -153,7 +153,7 @@ Use these questions to find the right first guide for your task.
 
 ### What Should I Read First?
 
-Use the [What Should I Read First?](../index.md#what-should-i-read-first)
+Use the [What Should I Read First?](/#what-should-i-read-first)
 table on the documentation overview page to pick the right starting point for
 your task.
 
diff --git a/docs/resources/troubleshooting/index.mdx b/docs/resources/troubleshooting/index.mdx
index c0c5e4ed..2b54bae1 100644
--- a/docs/resources/troubleshooting/index.mdx
+++ b/docs/resources/troubleshooting/index.mdx
@@ -10,7 +10,7 @@ Use this page when a NeMo Relay setup, build, or runtime workflow does not behav
 
 For trace incidents involving missing traces, wrong scope attachment, export
 failures, duplicate events, or sensitive telemetry, start with the
-[Trace Incident Runbook](trace-incident-runbook.md).
+[Trace Incident Runbook](/resources/troubleshooting/trace-incident-runbook).
 
 ## Package Or Build Setup Fails
 
diff --git a/justfile b/justfile
index a4d663e0..bb7b3aff 100644
--- a/justfile
+++ b/justfile
@@ -693,6 +693,7 @@ docs:
     generate_docs_api_references
     cd "$NEMO_RELAY_REPO_ROOT/fern"
     npx fern check --warnings
+    npx fern docs broken-links --strict
 
 # validate documentation links and navigation without a full site build
 docs-linkcheck:
@@ -702,6 +703,7 @@ docs-linkcheck:
     generate_docs_api_references
     cd "$NEMO_RELAY_REPO_ROOT/fern"
     npx fern check --warnings
+    npx fern docs broken-links --strict
 
 # regenerate the ignored Fern API reference pages
 docs-api-reference:
diff --git a/scripts/docs/generate_rust_library_reference.py b/scripts/docs/generate_rust_library_reference.py
index f8cef556..2a2b398c 100644
--- a/scripts/docs/generate_rust_library_reference.py
+++ b/scripts/docs/generate_rust_library_reference.py
@@ -132,6 +132,12 @@ def _slug_part(value: str) -> str:
     return value or "item"
 
 
+def _rustdoc_path_part(value: str) -> str:
+    value = value.replace("!", "-bang")
+    value = re.sub(r"[^A-Za-z0-9_-]+", "-", value)
+    return value.strip("-").lower() or "item"
+
+
 def _crate_slug(crate_name: str) -> str:
     return crate_name.replace("_", "-")
 
@@ -169,6 +175,16 @@ def _output_relative(crate_name: str, crate_dir: Path, html_path: Path) -> Path:
     return Path(crate_slug, *parent_parts, f"{_slug_part(stem)}.mdx")
 
 
+def _url_relative(crate_name: str, crate_dir: Path, html_path: Path) -> Path:
+    crate_slug = _crate_slug(crate_name)
+    rel = html_path.relative_to(crate_dir)
+    parent_parts = [_rustdoc_path_part(part) for part in rel.parent.parts]
+    if rel.name == "index.html":
+        return Path(crate_slug, *parent_parts, "index.mdx")
+    stem = rel.name.removesuffix(".html")
+    return Path(crate_slug, *parent_parts, f"{_slug_part(stem)}.mdx")
+
+
 def _page_url(output_rel: Path) -> str:
     without_suffix = output_rel.with_suffix("")
     parts = list(without_suffix.parts)
@@ -194,10 +210,11 @@ def _discover_pages(doc_root: Path, output_dir: Path) -> dict[Path, Page]:
             if 'id="main-content"' not in html_path.read_text(encoding="utf-8", errors="ignore"):
                 continue
             output_rel = _output_relative(crate_name, crate_dir, html_path)
+            url_rel = _url_relative(crate_name, crate_dir, html_path)
             pages[html_path.resolve()] = Page(
                 html_path=html_path.resolve(),
                 output_path=output_dir / output_rel,
-                url=_page_url(output_rel),
+                url=_page_url(url_rel),
                 crate_name=crate_name,
                 crate_dir_name=crate_dir_name,
             )