docs: backport #10173 to v3.3 + v3.4 & revise the content

website/docs/guides/markdown-features/markdown-features-intro.mdx

@@ -230,8 +230,6 @@ Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/
 
 :::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.
+You may want to keep your `<summary>` on a single line. Keep in mind that [MDX creates extra HTML `<p>` paragraphs for line breaks.](https://mdxjs.com/migrating/v2/#jsx). When in doubt, use the [MDX playground](https://mdxjs.com/playground/) to troubleshoot `<details>` rendering problems.
 
 :::

website/versioned_docs/version-3.3.2/guides/markdown-features/markdown-features-intro.mdx

@@ -181,42 +181,55 @@ 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 may want to keep your `<summary>` on a single line. Keep in mind that [MDX creates extra HTML `<p>` paragraphs for line breaks.](https://mdxjs.com/migrating/v2/#jsx). When in doubt, use the [MDX playground](https://mdxjs.com/playground/) to troubleshoot `<details>` rendering problems.
+
+:::

website/versioned_docs/version-3.4.0/guides/markdown-features/markdown-features-intro.mdx

@@ -230,8 +230,6 @@ Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/
 
 :::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.
+You may want to keep your `<summary>` on a single line. Keep in mind that [MDX creates extra HTML `<p>` paragraphs for line breaks.](https://mdxjs.com/migrating/v2/#jsx). When in doubt, use the [MDX playground](https://mdxjs.com/playground/) to troubleshoot `<details>` rendering problems.
 
 :::