diff --git a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
index 69784e5dc131..7f14c4726dc2 100644
--- a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
+++ b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
@@ -69,6 +69,28 @@ Some **content** with _markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
+## Usage with Prettier {#usage-with-prettier}
+
+If you use [Prettier](https://prettier.io) to format your Markdown files, Prettier might autoformat your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.
+
+<!-- prettier-ignore -->
+```md
+<!-- Prettier doesn't change this -->
+::: note
+
+Hello world
+
+:::
+
+<!-- Prettier changes this -->
+::: note 
+Hello world 
+:::
+
+<!-- to this -->
+::: note Hello world:::
+```
+
 ## Specifying title {#specifying-title}
 
 You may also specify an optional title