commonmark image media queries
Version 1.0.1
This CommonMark extension allows you to add media queries to images in your CommonMark-rendered Markdown.
You can install this extension via Composer:
composer require sven/commonmark-image-media-queriesTo enable this extension, first make sure the Attributes extension
that ships with CommonMark is enabled. Then, add it to the CommonMark environment:
use SvenCommonMarkImageMediaQueriesImageMediaQueriesExtension;
$environment->addExtension(new ImageMediaQueriesExtension());You can now add the media attribute to your images:
{media="(min-width: 800px)"}
{media="(min-width: 1200px)"}
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.
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 SvenCommonMarkImageMediaQueriesImageMediaQueriesExtension;
use SvenCommonMarkImageMediaQueriesShorthandsColorScheme;
$extension = new ImageMediaQueriesExtension();
$extension->addShorthand(new ColorScheme());
$environment->addExtension($extension);The SvenCommonMarkImageMediaQueriesShorthandsColorScheme shorthand allows you to use {scheme=dark} on an image,
and expands into (prefers-color-scheme: dark):
{scheme=dark}
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>The SvenCommonMarkImageMediaQueriesShorthandsWidth shorthand gives you the minw and maxw attributes to add to
an image. The example from above can then be shortened to the following:
{minw=800px}
{minw=1200px}
This of course also works the same with {maxw=[value]}.
To write your own shorthand, implement the SvenCommonMarkImageMediaQueriesShorthandsShorthand 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 SvenCommonMarkImageMediaQueriesShorthandsShorthand;
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 SvenCommonMarkImageMediaQueriesShorthandsConfigurationAwareShorthand interface instead
of the regular Shorthand interface if you would like access to the CommonMark configuration object.
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 LeagueCommonMarkEnvironmentEnvironment;
use SvenCommonMarkImageMediaQueriesImageMediaQueriesExtension;
$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.
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.
sven/commonmark-image-media-queries is licensed under the MIT License (MIT). Please see the license file
for more information.
