Code change:
<ins> // Test to check that the "warning blocks" are displayed as expected. go-to: "file://" + |DOC_PATH| + "/test_docs/struct.Foo.html" show-text: true define-function: ( "check-warning", (theme, color, border_color, background_color), block { set-local-storage: {"rustdoc-theme": |theme|, "rustdoc-use-system-theme": "false"} reload: // The IDs are added directly into the DOM to make writing this test easier. assert-css: ("#doc-warning-1", { "margin-bottom": "12px", "color": |color|, "border-left": "2px solid " + |border_color|, "background-color": |background_color|, }) assert-css: ("#doc-warning-2", { "margin-bottom": "0px", "color": |color|, "border-left": "2px solid " + |border_color|, "background-color": |background_color|, }) }, ) call-function: ("check-warning", { "theme": "ayu", "color": "rgb(197, 197, 197)", "border_color": "rgb(255, 142, 0)", "background_color": "rgba(0, 0, 0, 0)", }) call-function: ("check-warning", { "theme": "dark", "color": "rgb(221, 221, 221)", "border_color": "rgb(255, 142, 0)", "background_color": "rgba(0, 0, 0, 0)", }) call-function: ("check-warning", { "theme": "light", "color": "rgb(0, 0, 0)", "border_color": "rgb(255, 142, 0)", "background_color": "rgba(0, 0, 0, 0)", }) </ins>

Related discussion:
text: Among the suggested ideas, my favourite one remains the code block with "warning" as tag:
Yeah, but triple backticks is also for preformatted text without further markup, so you won't be able to e.g. use text formatting (or other code) in there
True... Finding the right syntax is much more complicated than expected...
That's the issue of using markdown, for all that it has a pretty nice baseline syntax it really was not designed for extensibility.
We can always use : it'd allow to have text formatting inside it.
I would use , it's not quite kosher to invent arbitrary HTML tags (though you can use Custom Elements, which is more heavyweight)
Sounds good to me. It's funny because we kinda came back to the . :rofl:
I just thought: we could use tag in the markdown and then transform it into in the generated HTML?
My main objection to all of these is that rustdoc shouldn't be adding custom markdown syntax that no one else supports. Any new syntax we use should look reasonable even if rendered with the default renderer.
Well, it remains valid markdown since it's HTML (even though it's custom tag). I'm completely fine with , but it might be simpler/better for users to simply write .
Coming back to this (because of ), it seems like the conversation kinda agreed on adding a CSS class directly and then it would look like this in the docs: . I'll send a PR in the next days and then we can open an FCP to see if everyone is ok with it (and if not, we'll have code to help the debate).
This indeed seems like a better solution than the HTML block. It also plays better with something said about not linking it too much too HTML. This will look like a proper warning or note, mostly independent of the HTML generation.
They also seemed to not be too favourable to anything that needs some extra parsing from rustdoc iuc. I'm fine with bot the github solution and the CSS class.
Maybe one more comment to make here. The note-taking app, which uses Markdown also has a similar syntax to create these blocks. It is called . It uses a syntax similar to the syntax that is used for doc intra-links currently, and it is fully compatible with them.