From 6227bb9370e784717b5370cf2d58231546f88020 Mon Sep 17 00:00:00 2001
From: Remco Haszing <remcohaszing@gmail.com>
Date: Fri, 29 Mar 2024 14:26:08 +0100
Subject: [PATCH] =?UTF-8?q?Add=20=E2=80=9CWhen=20should=20I=20use=20this?=
 =?UTF-8?q?=E2=80=9D=20section=20to=20the=20readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 536993f..855b4ed 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,9 @@ paths into imports.
 ## Table of Contents
 
 - [Installation](#installation)
+- [When should I use this?](#when-should-i-use-this)
 - [Usage](#usage)
+- [Example](#example)
 - [API](#api)
   - [Options](#options)
 - [Compatibility](#compatibility)
@@ -23,6 +25,21 @@ paths into imports.
 npm install rehype-mdx-import-media
 ```
 
+## When should I use this?
+
+You may want to author images in MDX using the markdown format, like so:
+
+```markdown
+![alt](./image.png 'title')
+```
+
+You may use MDX with a bundler such as [Webpack](https://webpack.js.org) or
+[Vite](http://vitejs.dev). By default bundlers don’t understand how to resolve those images. They
+only understand how to resolve imports. This plugin solves that problem.
+
+Also you may use MDX to load markdown files. If you reference other media in those markdown files
+using HTML tags, that media can be resolved by this plugin too.
+
 ## Usage
 
 This plugin takes HTML elements that refer to media content, and turns them into MDX expressions
@@ -41,7 +58,9 @@ nodes into an
 This may prevent other rehype plugins from further processing. To avoid this, put
 `rehype-mdx-import-media` after any other rehype plugins
 
-For example, given a file named `example.mdx` with the following contents:
+## Example
+
+Let’s say we have a file named `example.mdx` with the following contents:
 
 ```mdx
 ![](./image.png)