CommonMark Image Media Queries

This CommonMark extension allows you to add media queries to images in your CommonMark-rendered Markdown.

Installation

You can install this extension via Composer:

composer require sven/commonmark-image-media-queries

Usage

To enable this extension, first make sure the Attributes extension that ships with CommonMark is enabled. Then, add it to the CommonMark environment:

use Sven\CommonMark\ImageMediaQueries\ImageMediaQueriesExtension;

$environment->addExtension(new ImageMediaQueriesExtension());

You can now add the media attribute to your images:

![from 800px wide](/assets/800.jpg){media="(min-width: 800px)"}
![from 1200px wide](/assets/1200.jpg){media="(min-width: 1200px)"}
![An image](/assets/default.jpg)

This will render the following HTML:

<picture class="media-query-picture">
    <source srcset="/assets/800.jpg" media="(min-width: 800px)" />
    <source srcset="/assets/1200.jpg" media="(min-width: 1200px)" />
    <img src="/assets/default.jpg" alt="An image" />
</picture>

Important

The last image directly after at least one other image with a media attribute will always be used as the "default", and will thus be rendered as the <img /> tag in the <picture> element. If this last image has a media attribute itself, that attribute will not be used and be stripped away.

Shorthands

This extension also ships with, and allows you to write your own, shorthands for often-used media queries. You can enable a shorthand while registering the extension with CommonMark:

use Sven\CommonMark\ImageMediaQueries\ImageMediaQueriesExtension;
use Sven\CommonMark\ImageMediaQueries\Shorthands\ColorScheme;

$extension = new ImageMediaQueriesExtension();
$extension->addShorthand(new ColorScheme());

$environment->addExtension($extension);

Color Scheme

The \Sven\CommonMark\ImageMediaQueries\Shorthands\ColorScheme shorthand allows you to use {scheme=dark} on an image, and expands into (prefers-color-scheme: dark):

![dark](/assets/dark-settings.jpg){scheme=dark}
![A settings dialog](/assets/settings.jpg)

This will render the following HTML:

<picture class="media-query-picture">
    <source srcset="/assets/dark-settings.jpg" media="(prefers-color-scheme: dark)" />
    <img src="/assets/settings.jpg" alt="An image" />
</picture>

Width

The \Sven\CommonMark\ImageMediaQueries\Shorthands\Width shorthand gives you the minw and maxw attributes to add to an image. The example from above can then be shortened to the following:

![from 800px wide](/assets/800.jpg){minw=800px}
![from 1200px wide](/assets/1200.jpg){minw=1200px}
![An image](/assets/default.jpg)

This of course also works the same with {maxw=[value]}.

Writing your own

To write your own shorthand, implement the \Sven\CommonMark\ImageMediaQueries\Shorthands\Shorthand interface and return an array of queries keyed by their shorthand from the mediaQueries method. Any instances of {} in the query will be replaced by the value of the HTML attribute.

use Sven\CommonMark\ImageMediaQueries\Shorthands\Shorthand;

final class AspectRatio implements Shorthand
{
    public function mediaQueries(): iterable
    {
        return [
            'min-aspect' => '(min-aspect-ratio: {})',
            'max-aspect' => '(max-aspect-ratio: {})',
        ];
    }
}

If you then add the shorthand to the extension, you can use attributes like {min-aspect=8/5} and {max-aspect=3/2} on images in your Markdown.

Note

You can implement the \Sven\CommonMark\ImageMediaQueries\Shorthands\ConfigurationAwareShorthand interface instead of the regular Shorthand interface if you would like access to the CommonMark configuration object.

Configuration

By default, this extension adds the media-query-picture class to the <picture> element it renders. You can change this class in the configuration:

use League\CommonMark\Environment\Environment;
use Sven\CommonMark\ImageMediaQueries\ImageMediaQueriesExtension;

$environment = new Environment([
    'image_media_queries' => [
        'picture_class' => 'your-class', // Default: 'media-query-picture'.
    ],
]);

$environment->addExtension(new ImageMediaQueriesExtension());

Note: Remember that the <picture> element cannot be styled, because it is not actually rendered in the browser. You should style the <img> element instead. See the MDN page for more information.

Contributing

All contributions (pull requests, issues and feature requests) are welcome. Make sure to read through the CONTRIBUTING.md first, though. See the contributors page for all contributors.

License

sven/commonmark-image-media-queries is licensed under the MIT License (MIT). Please see the license file for more information.