simonvomeyser / commonmark-ext-lazy-image

Adds support for lazy images to the phpleague/commonmark package

Extension to render lazy images in markdown

This adds support for lazy images to the league/commonmark package version ^2.0.

Install

composer require simonvomeyser/commonmark-ext-lazy-image

⚠️ When you are using Version 1.0 of league\commonmark

The current version of this pacakge is only compatible with `League\CommonMark 2.0`, for `1.0` compatibility install the latest `1.0` version of this package like so:

composer require simonvomeyser/commonmark-ext-lazy-image "^v1.2.0"

You can find the old documentation here.

Example

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use SimonVomEyser\CommonMarkExtension\LazyImageExtension;

$environment = new Environment([]);
$environment->addExtension(new CommonMarkCoreExtension())
            ->addExtension(new LazyImageExtension());

$converter = new MarkdownConverter($environment);
$html = $converter->convert('![alt text](/path/to/image.jpg)');

This creates the following HTML

<img src="/path/to/image.jpg" alt="alt text" loading="lazy" />

Options/Configuration

By default, only the loading="lazy" attribute is added

While this should hopefully be sufficient in the future, you can use the provided options to integrate with various lazy loading libraries.

Here is an example how to use this package with the lozad library:

$environment = new Environment([
    // ... other config
    'lazy_image' => [
        'strip_src' => true, // remove the "src" to add it later via js, optional
        'html_class' => 'lozad', // the class that should be added, optional
        'data_attribute' => 'src', // how the data attribute is named that provides the source to get picked up by js, optional
    ]
]);
$environment->addExtension(new CommonMarkCoreExtension())
    ->addExtension(new LazyImageExtension());

$converter = new MarkdownConverter($environment);

$html = $converter->convert('![alt text](/path/to/image.jpg)');

This creates the following HTML

<img src="" alt="alt text" loading="lazy" data-src="/path/to/image.jpg" class="lozad" />