1 files changed, 25 insertions, 2 deletions
diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index b6f3ba1cfdd..f0dbfb854bb 100644
--- a/doc/user/markdown.md
+++ b/doc/user/markdown.md
@@ -1017,8 +1017,31 @@ Do not change to a reference style link.
 
 ![alt text](img/markdown_logo.png "Title Text")
 
-In the rare case where you must set a specific height or width for an image,
-you can use the `img` HTML tag instead of Markdown and set its `height` and
+#### Change the image dimensions
+
+> Introduced in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `markdown_image_attributes`. Disabled by default.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available,
+ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `markdown_image_attributes`.
+On GitLab.com, this feature is available.
+The feature is not ready for production use.
+
+You can control the width and height of an image by following the image with
+an attribute list.
+The value must an integer with a unit of either `px` (default) or `%`.
+
+For example
+
+```markdown
+![alt text](img/markdown_logo.png "Title Text"){width=100 height=100px}
+
+![alt text](img/markdown_logo.png "Title Text"){width=75%}
+```
+
+![alt text](img/markdown_logo.png "Title Text"){width=100 height=100px}
+
+You can also use the `img` HTML tag instead of Markdown and set its `height` and
 `width` parameters.
 
 #### Videos