markdown: don't nest a link inside a link

.github/workflows/main.yml

@@ -196,6 +196,7 @@ jobs:
     - run: cargo test -p wit-bindgen
     - run: cargo test -p wit-bindgen --all-features
     - run: cargo test -p wit-bindgen-rust
+    - run: cargo test -p wit-bindgen-markdown
     - run: cargo test --workspace --exclude 'wit-bindgen*'
     - run: rustup update nightly-2025-11-10 --no-self-update
     - run: rustup default nightly-2025-11-10

crates/markdown/src/lib.rs

@@ -1,6 +1,6 @@
 use anyhow::Result;
 use heck::*;
-use pulldown_cmark::{Event, LinkType, Parser, Tag, html};
+use pulldown_cmark::{Event, LinkType, Parser, Tag, TagEnd, html};
 use std::collections::HashMap;
 use std::fmt::Write;
 use wit_bindgen_core::{
@@ -207,20 +207,30 @@ impl WorldGenerator for Markdown {
         let world = &resolve.worlds[world];
         let parser = Parser::new(&self.src);
         let mut events = Vec::new();
+        // Named types are already written as links by `print_ty`, so track
+        // whether we're inside one: wrapping that code span again would nest
+        // an `<a>` inside an `<a>`, which isn't valid html. Markdown links
+        // can't nest, so a bool is enough here.
+        let mut in_link = false;
         for event in parser {
-            if let Event::Code(code) = &event {
-                if let Some(dst) = self.hrefs.get(code.as_ref()) {
-                    let tag = Tag::Link {
-                        link_type: LinkType::Inline,
-                        dest_url: dst.as_str().into(),
-                        title: "".into(),
-                        id: "".into(),
-                    };
-                    events.push(Event::Start(tag.clone()));
-                    events.push(event.clone());
-                    events.push(Event::End(tag.into()));
-                    continue;
+            match &event {
+                Event::Start(Tag::Link { .. }) => in_link = true,
+                Event::End(TagEnd::Link) => in_link = false,
+                Event::Code(code) if !in_link => {
+                    if let Some(dst) = self.hrefs.get(code.as_ref()) {
+                        let tag = Tag::Link {
+                            link_type: LinkType::Inline,
+                            dest_url: dst.as_str().into(),
+                            title: "".into(),
+                            id: "".into(),
+                        };
+                        events.push(Event::Start(tag.clone()));
+                        events.push(event.clone());
+                        events.push(Event::End(tag.into()));
+                        continue;
+                    }
                 }
+                _ => {}
             }
             events.push(event);
         }

crates/markdown/tests/codegen.rs

@@ -26,3 +26,38 @@ fn doc_line_starting_with_closing_brace() {
     let markdown = String::from_utf8(files.remove("w.md").unwrap()).unwrap();
     assert!(markdown.contains("\n  <p>}\n"));
 }
+
+#[test]
+fn type_links_are_not_nested_in_html() {
+    const WIT: &str = r#"
+        package a:b;
+
+        world w {
+          export x: interface {
+            record r {
+              f: u32,
+            }
+
+            g: func(a: r);
+          }
+        }
+    "#;
+
+    let mut resolve = Resolve::default();
+    let package = resolve.push_str("test.wit", WIT).unwrap();
+    let world = resolve.select_world(&[package], Some("w")).unwrap();
+    let mut files = Files::default();
+    let mut generator = wit_bindgen_markdown::Opts::default().build();
+
+    generator.generate(&mut resolve, world, &mut files).unwrap();
+
+    let html = String::from_utf8(files.remove("w.html").unwrap()).unwrap();
+    assert!(
+        html.contains(r##"<a href="#r"><code>r</code></a>"##),
+        "expected a single link to `r`:\n{html}"
+    );
+    assert!(
+        !html.contains(r##"<a href="#r"><a "##),
+        "link to `r` is nested inside another link:\n{html}"
+    );
+}