sven / commonmark-image-media-queries
Requires
- php: ^8.1
- league/commonmark: ^2.3
- league/config: ^1.2
- nette/schema: ^1.2
Requires (Dev)
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10.0
- spatie/phpunit-snapshot-assertions: ^5.0.1
This package is auto-updated.
Last update: 2024-11-28 17:49:26 UTC
README
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.