diff --git a/docs/.vuepress/configs/plugins.ts b/docs/.vuepress/configs/plugins.ts
index d39d16024e..486a42ddfe 100644
--- a/docs/.vuepress/configs/plugins.ts
+++ b/docs/.vuepress/configs/plugins.ts
@@ -51,6 +51,7 @@ export const plugins = [
figure: true,
mark: true,
size: true,
+ legacySize: true,
}),
markdownIncludePlugin({
deep: true,
diff --git a/docs/plugins/markdown/markdown-image.md b/docs/plugins/markdown/markdown-image.md
index cbe5323bf5..fb274a668c 100644
--- a/docs/plugins/markdown/markdown-image.md
+++ b/docs/plugins/markdown/markdown-image.md
@@ -68,6 +68,48 @@ interface ImageMarkOptions {
### Image Size
+You can use `|widthxheight` to specify the image size at the end of image alt.
+
+Both `width` and `height` should be number which means size in pixels, and both of them are optional (set `0` to indicate ignore).
+
+If you want the same behavior as Obsidian, you can pass `{ strict: true }` in plugin options. Now both `width` and `height` are both required to be set (one of them can be `0` to scale with radio according to the other).
+
+```md
+
+
+
+
+
+
+
+
+
+
+```
+
+will be parsed as:
+
+```html
+
+
+
+
+
+
+
+
+```
+
+### Image Size (legacy)
+
+::: tip
+
+You shall prefer the new grammar, as it's not breaking backward compatibility.
+
+The legacy grammar will break image rendering in environment that doesn't support it, such as GitHub.
+
+:::
+
You can use `=widthxheight` to specify the image size when setting `size: true` in plugin options.
```md
@@ -146,10 +188,10 @@ If the image is standalone in a line, wrapped or not wrapped by link, it will be
- Details:
Whether enable image size support.
-### obsidianSize
+### legacySize
- Type: `boolean`
-- Details: Whether enable Obsidian image size support.
+- Details: Whether enable legacy image size support.