From ca2f8da5f16892f100017d043866d12b87a13287 Mon Sep 17 00:00:00 2001
From: Guillaume Gomez <guillaume.gomez@huawei.com>
Date: Sat, 23 Dec 2023 11:15:00 +0100
Subject: [PATCH] Improve documentation for using warning blocks in
 documentation

---
 .../rustdoc/src/how-to-write-documentation.md    | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/src/doc/rustdoc/src/how-to-write-documentation.md b/src/doc/rustdoc/src/how-to-write-documentation.md
index acab1a93690c5..8994c01f82486 100644
--- a/src/doc/rustdoc/src/how-to-write-documentation.md
+++ b/src/doc/rustdoc/src/how-to-write-documentation.md
@@ -267,6 +267,22 @@ you can wrap it like this:
 /// more documentation
 ```
 
+Please note that if you want to put markdown in the HTML tag and for it to
+be interpreted as such, you need to have an empty line between the HTML tags
+and your markdown content. For example if you want to use a link:
+
+```md
+/// documentation
+///
+/// <div class="warning">
+///
+/// Go to [this link](https://rust-lang.org)!
+///
+/// </div>
+///
+/// more documentation
+```
+
 [`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/
 [commonmark markdown specification]: https://commonmark.org/
 [commonmark quick reference]: https://commonmark.org/help/