diff --git a/docs/api-resize.md b/docs/api-resize.md
index 6c76a6f6..20945e97 100644
--- a/docs/api-resize.md
+++ b/docs/api-resize.md
@@ -114,6 +114,15 @@ sharp(input)
   });
 ```
 
+```javascript
+const scaleByHalf = await sharp(input)
+  .metadata()
+  .then(({ width }) => sharp(input)
+    .resize(Math.round(width * 0.5))
+    .toBuffer()
+  );
+```
+
 -   Throws **[Error][13]** Invalid parameters
 
 Returns **Sharp** 
diff --git a/lib/resize.js b/lib/resize.js
index 0aafd5af..13e881fd 100644
--- a/lib/resize.js
+++ b/lib/resize.js
@@ -173,6 +173,14 @@ const mapFitToCanvas = {
  *     // and no larger than the input image
  *   });
  *
+ * @example
+ * const scaleByHalf = await sharp(input)
+ *   .metadata()
+ *   .then(({ width }) => sharp(input)
+ *     .resize(Math.round(width * 0.5))
+ *     .toBuffer()
+ *   );
+ *
  * @param {Number} [width] - pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
  * @param {Number} [height] - pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
  * @param {Object} [options]