Fix broken internal links in API doc generator

Re-exported items from private internal modules (e.g. std::thread::Builder
from std::thread::builder) were missing pages and had broken links because
the doc generator skipped page creation for "LocalPublic" re-exports,
assuming pages existed at the original definition path.

Three categories of fixes:

- Create pages at re-export locations for LocalPublic items, not just
  NeedsPage. Only skip page creation for External (cross-crate) items.
  Fix html_path computation for Use items to include the target's kind
  prefix (struct., fn., etc.).

- Use rustdoc JSON's pre-resolved `links` field for intra-doc link
  resolution, so links like `spawn` and `Builder` resolve to the correct
  item in the current module rather than an arbitrary match from another
  crate (e.g. tokio::spawn or regex_automata::Builder).

- Handle methods and enum variants in link resolution: methods link to
  their parent type page with #method.name anchors, and enum variants
  link to the parent enum page with #variant.Name anchors.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: brson

crates/rustmax-rustdoc/src/output.rs

@@ -60,13 +60,15 @@ fn write_item(ctx: &RenderContext, item: &crate::types::RenderableItem) -> AnyRe
         }
         let target_id = use_item.id.as_ref().unwrap();
 
-        // Skip page creation if target has a public page elsewhere.
+        // Skip page creation only for external crates (they have their own pages).
+        // LocalPublic items may be defined in private modules with no rendered page,
+        // so we always create a page at the re-export location.
         match ctx.reexport_target(target_id) {
-            ReexportTarget::LocalPublic { .. } | ReexportTarget::External { .. } => {
+            ReexportTarget::External { .. } => {
                 return Ok(());
             }
-            ReexportTarget::NeedsPage => {
-                // Proceed with page creation.
+            ReexportTarget::LocalPublic { .. } | ReexportTarget::NeedsPage => {
+                // Proceed with page creation at the re-export location.
             }
         }
 

crates/rustmax-rustdoc/src/render/markdown.rs

@@ -1,5 +1,7 @@
 //! Markdown to HTML rendering with syntax highlighting and intra-doc link resolution.
 
+use std::collections::HashMap;
+
 use comrak::{markdown_to_html_with_plugins, Arena, Options, Plugins};
 use comrak::adapters::SyntaxHighlighterAdapter;
 use comrak::nodes::NodeValue;
@@ -23,12 +25,16 @@ pub fn render_markdown(md: &str, highlighter: &Highlighter) -> String {
 ///
 /// Resolves Rust path references like `` [`Vec`] `` or `[text](std::option::Option)`
 /// to actual HTML documentation URLs.
+///
+/// `pre_resolved_links` maps link text to pre-resolved URLs from the item's
+/// rustdoc JSON `links` field. These take priority over global index resolution.
 pub fn render_markdown_with_links(
     md: &str,
     highlighter: &Highlighter,
     global_index: Option<&GlobalItemIndex>,
     current_crate: &str,
     current_depth: usize,
+    pre_resolved_links: &HashMap<String, String>,
 ) -> String {
     let Some(index) = global_index else {
         return render_markdown(md, highlighter);
@@ -46,7 +52,10 @@ pub fn render_markdown_with_links(
     for node in root.descendants() {
         let mut data = node.data.borrow_mut();
         if let NodeValue::Link(ref mut link) = data.value {
-            if is_rust_path(&link.url) {
+            // Check pre-resolved links first (from rustdoc's links field).
+            if let Some(url) = pre_resolved_links.get(&link.url) {
+                link.url = url.clone();
+            } else if is_rust_path(&link.url) {
                 if let Some(resolved) = resolve_rust_path(&link.url, index, current_crate, current_depth) {
                     link.url = resolved;
                 } else {
@@ -459,6 +468,7 @@ pub fn render_short_doc(
     global_index: Option<&GlobalItemIndex>,
     current_crate: &str,
     current_depth: usize,
+    pre_resolved_links: &HashMap<String, String>,
 ) -> String {
     let ref_defs = extract_reference_definitions(full_docs);
     let first_para = extract_first_paragraph(full_docs);
@@ -475,6 +485,7 @@ pub fn render_short_doc(
         global_index,
         current_crate,
         current_depth,
+        pre_resolved_links,
     );
 
     strip_paragraph_wrapper(&html)

crates/rustmax-rustdoc/src/render/mod.rs

@@ -9,12 +9,13 @@ pub mod sidebar;
 
 use rmx::prelude::*;
 use rmx::tera::Tera;
-use rustdoc_types::{Crate, Id, ItemKind, Visibility};
+use rustdoc_types::{Crate, Id, ItemEnum, ItemKind, Visibility};
 use std::collections::HashMap;
+use std::hash::BuildHasher;
 use std::path::PathBuf;
 
 use crate::{RenderConfig, ModuleTree, GlobalItemIndex};
-use crate::types::{build_module_tree, build_impl_index, ImplIndex};
+use crate::types::{build_module_tree, build_impl_index, get_type_id, ImplIndex};
 
 /// Where a re-export target's page exists.
 pub enum ReexportTarget {
@@ -177,30 +178,201 @@ impl<'a> RenderContext<'a> {
         Some(url)
     }
 
+    /// Pre-resolve an item's `links` field into a URL map.
+    ///
+    /// Takes the item's `links` field (mapping link text to item IDs) and resolves
+    /// each ID to an actual HTML URL. The keys are normalized to strip backtick
+    /// wrappers since the markdown preprocessor strips them.
+    pub fn resolve_item_links<S: BuildHasher>(
+        &self,
+        links: &std::collections::HashMap<String, Id, S>,
+        current_depth: usize,
+    ) -> HashMap<String, String> {
+        let mut resolved = HashMap::new();
+        for (text, id) in links {
+            if let Some(url) = self.resolve_reexport_url(id, current_depth) {
+                // The links field keys may have backtick wrappers (`` `Builder` ``).
+                // Strip them since preprocess_shortcut_links removes them from URLs.
+                let clean_key = text.trim_matches('`').to_string();
+                resolved.insert(clean_key, url);
+            }
+        }
+        resolved
+    }
+
+    /// Resolve an item ID to a URL, preferring the re-export location.
+    ///
+    /// Handles types, modules, methods, and enum variants.
+    fn resolve_reexport_url(&self, id: &Id, current_depth: usize) -> Option<String> {
+        // First check krate.paths (has types, modules, variants, but not methods).
+        if let Some(summary) = self.krate.paths.get(id) {
+            // Handle enum variants: link to parent enum page with #variant.Name anchor.
+            if summary.kind == ItemKind::Variant {
+                return self.resolve_variant_url(&summary.path, summary.crate_id, current_depth);
+            }
+
+            if summary.crate_id == 0 {
+                // Local item. Check if it's re-exported to a public-facing location.
+                if let Some(url) = self.find_reexport_url(id, summary.kind, current_depth) {
+                    return Some(url);
+                }
+                // Fall back to definition path.
+                return self.build_item_url(&summary.path, summary.kind, current_depth);
+            } else {
+                // Cross-crate item.
+                return self.resolve_cross_crate_url(&summary.path, current_depth);
+            }
+        }
+
+        // Not in paths - check if it's a method/associated item in the index.
+        if let Some(item) = self.krate.index.get(id) {
+            if matches!(item.inner, ItemEnum::Function(_)) {
+                return self.resolve_method_url(id, item, current_depth);
+            }
+        }
+
+        None
+    }
+
+    /// Resolve an enum variant to a URL with #variant.Name anchor.
+    fn resolve_variant_url(
+        &self,
+        variant_path: &[String],
+        crate_id: u32,
+        current_depth: usize,
+    ) -> Option<String> {
+        if variant_path.len() < 2 {
+            return None;
+        }
+        // Path is like ["core", "result", "Result", "Ok"].
+        // Parent enum path is everything except last segment.
+        let enum_path = &variant_path[..variant_path.len() - 1];
+        let variant_name = variant_path.last()?;
+
+        let enum_url = if crate_id == 0 {
+            self.build_item_url(enum_path, ItemKind::Enum, current_depth)?
+        } else {
+            self.resolve_cross_crate_url(enum_path, current_depth)
+                .or_else(|| self.build_item_url(enum_path, ItemKind::Enum, current_depth))?
+        };
+
+        Some(format!("{}#variant.{}", enum_url, variant_name))
+    }
+
+    /// Resolve a method/associated function to a URL with #method.name anchor.
+    fn resolve_method_url(
+        &self,
+        method_id: &Id,
+        method_item: &rustdoc_types::Item,
+        current_depth: usize,
+    ) -> Option<String> {
+        let method_name = method_item.name.as_deref()?;
+
+        // Find the parent type by searching impl blocks.
+        for (_impl_id, impl_item) in &self.krate.index {
+            let ItemEnum::Impl(impl_) = &impl_item.inner else {
+                continue;
+            };
+            if !impl_.items.contains(method_id) {
+                continue;
+            }
+            // Found the impl containing this method.
+            // Get the type ID from the impl's for_ type.
+            if let Some(type_id) = get_type_id(&impl_.for_) {
+                if let Some(type_url) = self.resolve_reexport_url(type_id, current_depth) {
+                    // Strip any existing fragment.
+                    let base_url = type_url.split('#').next().unwrap_or(&type_url);
+                    return Some(format!("{}#method.{}", base_url, method_name));
+                }
+            }
+            break;
+        }
+
+        None
+    }
+
+    /// Find a re-export URL for a local item by checking if it appears as a
+    /// Use target in the module tree.
+    fn find_reexport_url(
+        &self,
+        target_id: &Id,
+        kind: ItemKind,
+        current_depth: usize,
+    ) -> Option<String> {
+        // Walk the module tree looking for Use items targeting this ID.
+        self.find_reexport_in_tree(&self.module_tree, target_id, kind, current_depth)
+    }
+
+    fn find_reexport_in_tree(
+        &self,
+        tree: &crate::types::ModuleTree,
+        target_id: &Id,
+        kind: ItemKind,
+        current_depth: usize,
+    ) -> Option<String> {
+        for item in &tree.items {
+            if let ItemEnum::Use(use_item) = &item.item.inner {
+                if use_item.id.as_ref() == Some(target_id) {
+                    return self.build_item_url(&item.path, kind, current_depth);
+                }
+            }
+        }
+        for sub in &tree.submodules {
+            if let Some(url) = self.find_reexport_in_tree(sub, target_id, kind, current_depth) {
+                return Some(url);
+            }
+        }
+        None
+    }
+
     /// Render markdown to HTML.
     pub fn render_markdown(&self, md: &str) -> String {
         markdown::render_markdown(md, &self.highlighter)
     }
 
     /// Render markdown to HTML with intra-doc link resolution.
     pub fn render_markdown_with_links(&self, md: &str, current_depth: usize) -> String {
+        let empty = HashMap::new();
+        self.render_markdown_with_item_links(md, current_depth, &empty)
+    }
+
+    /// Render markdown to HTML with intra-doc link resolution and pre-resolved item links.
+    pub fn render_markdown_with_item_links(
+        &self,
+        md: &str,
+        current_depth: usize,
+        pre_resolved_links: &HashMap<String, String>,
+    ) -> String {
         markdown::render_markdown_with_links(
             md,
             &self.highlighter,
             self.global_index,
             self.crate_name(),
             current_depth,
+            pre_resolved_links,
         )
     }
 
     /// Render a short documentation string (first paragraph only) as inline HTML.
     pub fn render_short_doc(&self, full_docs: &str, current_depth: usize) -> String {
+        let empty = HashMap::new();
+        self.render_short_doc_with_item_links(full_docs, current_depth, &empty)
+    }
+
+    /// Render a short doc string with pre-resolved item links.
+    pub fn render_short_doc_with_item_links(
+        &self,
+        full_docs: &str,
+        current_depth: usize,
+        pre_resolved_links: &HashMap<String, String>,
+    ) -> String {
         markdown::render_short_doc(
             full_docs,
             &self.highlighter,
             self.global_index,
             self.crate_name(),
             current_depth,
+            pre_resolved_links,
         )
     }
 

crates/rustmax-rustdoc/src/render/module.rs

@@ -42,10 +42,15 @@ pub fn render_module(ctx: &RenderContext, tree: &ModuleTree) -> AnyResult<String
     let depth = path.len();
     let path_to_root = if depth == 0 { String::new() } else { "../".repeat(depth) };
 
+    // Pre-resolve links from the module item's links field.
+    let item_links = tree.module_item.as_ref()
+        .map(|m| ctx.resolve_item_links(&m.item.links, depth))
+        .unwrap_or_default();
+
     // Module documentation.
     let docs = tree.module_item.as_ref()
         .and_then(|m| m.item.docs.as_ref())
-        .map(|d| ctx.render_markdown_with_links(d, depth))
+        .map(|d| ctx.render_markdown_with_item_links(d, depth, &item_links))
         .unwrap_or_default();
     tera_ctx.insert("docs", &docs);
 
@@ -84,24 +89,24 @@ pub fn render_module(ctx: &RenderContext, tree: &ModuleTree) -> AnyResult<String
 
             // Determine link URL.
             let item_url = match ctx.reexport_target(target_id) {
-                ReexportTarget::LocalPublic { ref path, kind }
-                | ReexportTarget::External { ref path, kind } => {
-                    // Link to original.
+                ReexportTarget::External { ref path, kind } => {
+                    // Link to external crate's page.
                     ctx.build_item_url(path, kind, depth).unwrap_or_default()
                 }
-                ReexportTarget::NeedsPage => {
-                    // Link to re-export's page.
+                ReexportTarget::LocalPublic { .. } | ReexportTarget::NeedsPage => {
+                    // Link to re-export's page at re-export location.
                     format!("{}{}", path_to_root, item.html_path.display())
                 }
             };
 
             // Try to get target from index first, then fall back to paths.
             if let Some(target_item) = ctx.krate.index.get(target_id) {
+                let target_links = ctx.resolve_item_links(&target_item.links, depth);
                 let summary = ItemSummary {
                     name: use_item.name.clone(),
                     path: item_url,
                     short_doc: target_item.docs.as_ref()
-                        .map(|d| ctx.render_short_doc(d, depth))
+                        .map(|d| ctx.render_short_doc_with_item_links(d, depth, &target_links))
                         .unwrap_or_default(),
                 };
 

crates/rustmax-rustdoc/src/types.rs

@@ -145,8 +145,18 @@ fn build_tree_recursive<'a>(
                 submodules.push(subtree);
             }
             _ => {
-                // Regular item.
-                let html_path = path_to_html(&child_path, item_kind(&child_item.inner));
+                // Regular item. For re-exports, determine kind from target.
+                let kind = match &child_item.inner {
+                    ItemEnum::Use(use_item) => {
+                        use_item.id.as_ref().and_then(|target_id| {
+                            krate.index.get(target_id)
+                                .and_then(|t| item_kind(&t.inner))
+                                .or_else(|| krate.paths.get(target_id).map(|s| s.kind))
+                        })
+                    }
+                    other => item_kind(other),
+                };
+                let html_path = path_to_html(&child_path, kind);
                 items.push(RenderableItem {
                     id: child_id,
                     item: child_item,
@@ -336,7 +346,7 @@ pub fn build_impl_index<'a>(krate: &'a Crate) -> ImplIndex<'a> {
 }
 
 /// Try to extract the ID from a Type (works for resolved paths).
-fn get_type_id(ty: &Type) -> Option<&Id> {
+pub fn get_type_id(ty: &Type) -> Option<&Id> {
     match ty {
         Type::ResolvedPath(path) => Some(&path.id),
         _ => None,