# \[Pre-RFC\] Markdown alerts for documentation **URL:** \ **Category:** documentation\ **Created:** [June 13, 2025, 8:11am UTC](https://internals.rust-lang.org/t/pre-rfc-markdown-alerts-for-documentation/23086 "2025-06-13T08:11:41Z")\ **Posts on this page:** 4\ **Page:** 1
**Author:** ![Sanpi](https://avatars.discourse-cdn.com/v4/letter/s/d78d45/32.png) [@Sanpi](https://internals.rust-lang.org/u/Sanpi)\ **Post date:** [June 13, 2025, 8:11am UTC](https://internals.rust-lang.org/t/pre-rfc-markdown-alerts-for-documentation/23086/1 "2025-06-13T08:11:41Z")
- Feature Name: `doc_gfm_alerts` - Start Date: 2025-06-13 - RFC PR: - Rust Issue: # Summary Adding github compatible markdown alerts to rust documenation. # Motivation - Uses a markdown like syntax instead of html; - Adding more kind of alerts for rust documentation; - More consistent render beetween docs.rs and github. # Guide-level explanation In one hand, github has added a new extension to its markdown syntax : [New Markdown extension: Alerts provide distinctive styling for significant content](https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/). This extension allows adding a flaword to a comment like note, warning, caution… ![Markdown alerts overview](https://github.blog/wp-content/uploads/2023/12/290547405-0505deff-ff73-44f4-9f47-1d39b2f1d8cd.png?w=1024) In another hand, rustdoc have the possibility to [add a warning bloc](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#adding-a-warning-block) in html. This RFC proposes to add the github alert extension to rustdoc: ```markdown > [!NOTE] > Useful information that users should know, even when skimming content. > [!TIP] > Helpful advice for doing things better or more easily. > [!IMPORTANT] > Key information users need to know to achieve their goal. > [!WARNING] > Urgent info that needs immediate user attention to avoid problems. > [!CAUTION] > Advises about risks or negative outcomes of certain actions. ``` # Reference-level explanation The generated HTML code could be compatible with the current warning block: ```html
``` The `pulldown-cmark` crate supports this since the 0.11 release: [https://github.com/pulldown-cmark/pulldown-cmark/issues/718](https://github.com/pulldown-cmark/pulldown-cmark/issues/718). # Drawbacks - # Rationale and alternatives This syntax is also available on [Microsoft Learn](https://learn.microsoft.com/en-us/contribute/content/markdown-reference#alerts-note-tip-important-caution-warning) and gitlab. # Prior art - # Unresolved questions - This feature require modifying the current markdown parser, currently this syntax is for link with item: ```rust warning: unresolved link to `!NOTE` --> src/main.rs:2:7 | 2 | * > [!NOTE] | ^^^^^ no item named `!NOTE` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default ``` How should this breaking change be handled? - Is unknow alert kind should be disallowed or just a warning and converted to a div with this arbitrary class? # Future possibilities - Render alerts in README on [crates.io](http://crates.io) ---
**Author:** ![kornel](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/kornel/32/2711_2.png) [@kornel](https://internals.rust-lang.org/u/kornel)\ **Post date:** [June 13, 2025, 5:14pm UTC](https://internals.rust-lang.org/t/pre-rfc-markdown-alerts-for-documentation/23086/2 "2025-06-13T17:14:02Z")
This has been considered, and rustdoc got support for warnings, but using a different approach: > > > Following https://github.com/rust-lang/rust/pull/79677, we realized that rustdoc… users would prefer to have a syntax extension rather than using plain HTML to have warning blocks. > > @dtolnay suggested the following: > > \`\`\`text > /// WARNING: it doesn't work yet. > \`\`\` > > @Darksonn suggested: > > \`\`\`text > \[\[info\]\] > | Many of Tokio's types are named the same as their synchronous equivalent in > | the Rust standard library. When it makes sense, Tokio exposes the same APIs > | as \`std\` but using \`async fn\`. > \`\`\` > > What do you think? > > cc @rust-lang/rustdoc ---
**Author:** ![Sanpi](https://avatars.discourse-cdn.com/v4/letter/s/d78d45/32.png) [@Sanpi](https://internals.rust-lang.org/u/Sanpi)\ **Post date:** [June 13, 2025, 6:17pm UTC](https://internals.rust-lang.org/t/pre-rfc-markdown-alerts-for-documentation/23086/3 "2025-06-13T18:17:06Z")
Thank you for the reference. Now that there's a de facto standard, it might be a good idea to relaunch this proposal? ---
**Author:** ![Nemo157](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nemo157/32/11585_2.png) [@Nemo157](https://internals.rust-lang.org/u/Nemo157)\ **Post date:** [June 14, 2025, 7:18am UTC](https://internals.rust-lang.org/t/pre-rfc-markdown-alerts-for-documentation/23086/4 "2025-06-14T07:18:32Z")
> [@Sanpi](#): > > Now that there's a de facto standard, it might be a good idea to relaunch this proposal? GFM alerts already existed back when the rustdoc feature was considered and was discussed as an alternative in the implementing PR: > > > Fixes https://github.com/rust-lang/rust/issues/79710. > > You can test it \[here\](…https://rustdoc.crud.net/imperio/warning-block/foo/struct.Foo.html). It currently looks like this: > > !\[image\](https://user-images.githubusercontent.com/3050060/211413494-e1cf04e4-c081-4a9d-97db-27329405cfa7.png) > > So a few things to note: > > \* Since it's a new add and it's changing the UI, we'll need to go through an FCP. > \* Does the UI looks good? > \* Is the way picked to add a warning block ok for everyone? The discussion on the issue seemed to be in favour of this solution but it doesn't hurt to double-check. > > cc @rust-lang/rustdoc