Marked Responsive Images


An extension for Marked (github, npm) designed to generate responsive images by injecting srcset and sizes attributes based on simple filename conventions.

Marked Responsive Images parses image filenames to detect available size and file extension variants without breaking standard markdown compatibility.

Installation

``bash
npm install marked-responsive-images
`

Usage

`javascript
// Default factory export (recommended)
import { marked } from 'marked';
import markedResponsiveImages from 'marked-responsive-images';

/*
// or use UMD scripts


*/

// Register with marked
marked.use(markedResponsiveImages());

// Render markdown
const html = marked.parse('!My Image');
`

> [!NOTE]
> If a variant exists with the same dimensions but a different extension (for example webp alongside a jpg), the variant will be used in the srcset and the original extension will be omitted for better performance on modern browsers.

Naming Convention

$3

The extension looks for a specific pattern at the end of your filenames to generate the srcset.

Pattern: filename__width-height_width-height-extension[…].png

1. Separator:
Use two underscores (__) to separate the base name from the sizes.
2. Variants:
Use one underscore (_) to separate different size variants.
3. Dimensions:
Use a dash (-) to separate width and height.
4. [optional] Extension:
Use a second dash (-) to specify a file extension if it is different from the one used by the URL.

> [!NOTE]
> The "full name" image must exist on your server.
> The image path you write in Markdown (e.g., hero__400-300_800-600.jpg) is used as the graceful fallback. This file is assigned to the src attribute and will be the only image loaded if the extension is disabled or if the Markdown is viewed in an environment that doesn't support responsive images.

> [!IMPORTANT]
> This extension does not resize images.
> It is your responsibility to ensure that all physical image files—both the "Full Name" fallback and the individual variants (e.g., hero__400-300.jpg)—actually exist at the destination. This extension only generates the HTML markup to point to them.

$3

#### Basic Resizing:

- Markdown:
`md
!Responsive image example
`
- Resulting HTML:
`html
class="md-img"
src="img/photo__400-300_800-600.jpg"
srcset="img/photo__400-300.jpg 400w, img/photo__800-600.jpg 800w"
width="800"
height="600"
alt="Responsive image example"
/>
`

#### Format Switching:

- Markdown:
`md
!Web optimized photo example
`
- Resulting HTML:
`html
class="md-img"
src="img/photo__800-600-webp.jpg"
srcset="img/photo__800-600.webp 800w"
width="800"
height="600"
alt="Web optimized photo example"
/>
`

Configuration

You can configure global options for Marked Responsive Images using:

`js
marked.use(
markedResponsiveImages({
sizes: null, // {string}
lazy: true, // {boolean}
debug: false, // {boolean}
}),
);
`

| Option | Type | Default | Description |
| :------ | :-------- | :------ | :------------------------------------------------------------------------------- |
| sizes | string | null | The sizes attribute that should be added to generate tags. |
| lazy | boolean | true | Adds loading="lazy" to images for better page load optimization. |
| debug | boolean | false` | Log warnings to the console when URLs cannot be parsed or formats are malformed. |