Repository: rust-lang/rust (Rust)

Issue:
Rustdoc reports `broken-intra-doc-links` for Github-flavored Markdown admonitions like `[!IMPORTANT]`
<!--
Thank you for filing a bug report! 🐛 Please provide a short summary of the bug,
along with any information you feel relevant to replicating the bug.
-->

I tried this code:

```rust
#![doc = include_str!("../README.md")]
```

```markdown
> [!IMPORTANT]
> This is an important message
```

I expected to see this happen: Rustdoc at least generating documentation (perhaps not with specialized support for the `[!FOO]` syntax, but at least not error)

Instead, this happened: With `env RUSTFLAGS="-D warnings"`, rustdoc errored with `unresolved link to '!NOTICE'`

### Meta
<!--
If you're using the stable version of the compiler, you should also check if the
bug also exists in the beta or nightly versions.
-->

`rustc --version --verbose`:
```
rustc 1.89.0-nightly (6f6971078 2025-05-28)
binary: rustc
commit-hash: 6f69710780d579b180ab38da4c1384d630f7bd31
commit-date: 2025-05-28
host: x86_64-unknown-linux-gnu
release: 1.89.0-nightly
LLVM version: 20.1.5
```

`rustdoc --version --verbose`:
```
rustdoc 1.89.0-nightly (6f6971078 2025-05-28)
binary: rustdoc
commit-hash: 6f69710780d579b180ab38da4c1384d630f7bd31
commit-date: 2025-05-28
host: x86_64-unknown-linux-gnu
release: 1.89.0-nightly
LLVM version: 20.1.5
```



Discussion:
We actually already suppress this lint on shortcut-style links specifically in some cases, so i guess it wouldn't be the worst to suppress them in a few other cases, i guess?
Yeah, especially given that there are a finite number of them: https://github.com/orgs/community/discussions/16925

If you point me in the right direction as to where to look for this, I'm happy to submit a PR :)
it's in `preprocess_link` in `passes/collect_intra_doc_links.rs`.

we could probably just look for the `!` at the start for shortcut links specifically (collapsed links and all the other ones are pretty unambiguous)
This should be pretty easy to implement once https://github.com/rust-lang/rust/pull/132748 gets merged.



Patch:
diff --git a/src/librustdoc/passes/collect_intra_doc_links.rs b/src/librustdoc/passes/collect_intra_doc_links.rs
index c9fa3a4837f29..8b51066bf2f3d 100644
--- a/src/librustdoc/passes/collect_intra_doc_links.rs
+++ b/src/librustdoc/passes/collect_intra_doc_links.rs
@@ -997,6 +997,7 @@ fn preprocess_link(
         }
     };
 
+    let is_shortcut_style = ori_link.kind == LinkType::ShortcutUnknown;
     // If there's no backticks, be lenient and revert to the old behavior.
     // This is to prevent churn by linting on stuff that isn't meant to be a link.
     // only shortcut links have simple enough syntax that they
@@ -1013,11 +1014,22 @@ fn preprocess_link(
     // | has backtick |    never ignore    |    never ignore   |
     // | no backtick  | ignore if url-like |    never ignore   |
     // |-------------------------------------------------------|
-    let ignore_urllike =
-        can_be_url || (ori_link.kind == LinkType::ShortcutUnknown && !ori_link.link.contains('`'));
+    let ignore_urllike = can_be_url || (is_shortcut_style && !ori_link.link.contains('`'));
     if ignore_urllike && should_ignore_link(path_str) {
         return None;
     }
+    // If we have an intra-doc link starting with `!` (which isn't `[!]` because this is the never type), we ignore it
+    // as it is never valid.
+    //
+    // The case is common enough because of cases like `#[doc = include_str!("../README.md")]` which often
+    // uses GitHub-flavored Markdown (GFM) admonitions, such as `[!NOTE]`.
+    if is_shortcut_style
+        && let Some(suffix) = ori_link.link.strip_prefix('!')
+        && !suffix.is_empty()
+        && suffix.chars().all(|c| c.is_ascii_alphabetic())
+    {
+        return None;
+    }
 
     // Strip generics from the path.
     let path_str = match strip_generics_from_path(path_str) {


Test patch:
diff --git a/tests/rustdoc-ui/intra-doc/github-flavored-admonitions.rs b/tests/rustdoc-ui/intra-doc/github-flavored-admonitions.rs
new file mode 100644
index 0000000000000..d5fa72eb993f9
--- /dev/null
+++ b/tests/rustdoc-ui/intra-doc/github-flavored-admonitions.rs
@@ -0,0 +1,6 @@
+// regression test for https://github.com/rust-lang/rust/issues/141866
+//@ check-pass
+#![deny(rustdoc::broken_intra_doc_links)]
+
+//! > [!NOTE]
+//! > This should not cause any warnings