From 3c0d6b12eba5faf3cda1e49334ac3b10d9de2470 Mon Sep 17 00:00:00 2001
From: Tatsunori Uchino <tats.u@live.jp>
Date: Sat, 25 May 2024 23:23:38 +0900
Subject: [PATCH] docs: backport #10173 to v3.3

---
 .../markdown-features-intro.mdx               | 63 ++++++++++++-------
 1 file changed, 39 insertions(+), 24 deletions(-)

diff --git a/website/versioned_docs/version-3.3.2/guides/markdown-features/markdown-features-intro.mdx b/website/versioned_docs/version-3.3.2/guides/markdown-features/markdown-features-intro.mdx
index b6bcd756beff..52a6866914b9 100644
--- a/website/versioned_docs/version-3.3.2/guides/markdown-features/markdown-features-intro.mdx
+++ b/website/versioned_docs/version-3.3.2/guides/markdown-features/markdown-features-intro.mdx
@@ -181,42 +181,57 @@ Markdown quotes are beautifully styled:
 
 Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) HTML elements are beautifully styled:
 
-```md
+{/* prettier-ignore */}
+````md
 ### Details element example
 
 <details>
   <summary>Toggle me!</summary>
-  <div>
-    <div>This is the detailed content</div>
-    <br/>
-    <details>
-      <summary>
-        Nested toggle! Some surprise inside...
-      </summary>
-      <div>😲😲😲😲😲</div>
-    </details>
-  </div>
+
+  This is the detailed content
+
+  ```js
+  console.log("Markdown features including the code block are available");
+  ```
+
+  You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.io)
+  <details>
+    <summary>Nested toggle! Some surprise inside...</summary>
+
+    😲😲😲😲😲
+  </details>
 </details>
-```
+````
 
-```mdx-code-block
+````mdx-code-block
 <BrowserWindow>
 
 <h3>Details element example</h3>
 
 <details>
   <summary>Toggle me!</summary>
-  <div>
-    <div>This is the detailed content</div>
-    <br/>
-    <details>
-      <summary>
-        Nested toggle! Some surprise inside...
-      </summary>
-      <div>😲😲😲😲😲</div>
-    </details>
-  </div>
+
+  This is the detailed content
+
+  ```js
+  console.log("Markdown features including the code block are available");
+  ```
+
+  You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.io)
+  <details>
+    <summary>Nested toggle! Some surprise inside...</summary>
+
+    😲😲😲😲😲
+  </details>
 </details>
 
 </BrowserWindow>
-```
+````
+
+:::info
+
+- You should not break lines between the starting or ending tag of the `<summary>` element and its content or an extra `<p>` element is inserted.
+- Blank lines between the `<summary>` element and the first paragraph of the detailed content are optional in Docusaurus but strongly recommended to ensure MDX portability with other site generators.
+- Blank lines between the nested `<details>` element and the paragraphs just around it are optional.
+
+:::