- 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.
This extension allows adding a flaword to a comment like note, warning, caution…
In another hand, rustdoc have the possibility to add a warning bloc in html.
This RFC proposes to add the github alert extension to rustdoc:
> [!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:
<div class="note"></div>
<div class="tip"></div>
<div class="important"></div>
<div class="warning"></div>
<div class="caution"></div>
The pulldown-cmark crate supports this since the 0.11 release:
https://github.com/pulldown-cmark/pulldown-cmark/issues/718.
Drawbacks
-
Rationale and alternatives
This syntax is also available on Microsoft Learn and gitlab.
Prior art
-
Unresolved questions
- This feature require modifying the current markdown parser, currently this syntax is for link with item:
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