sven/commonmark-dark-mode-images

This package is abandoned and no longer maintained. The author suggests using the sven/commonmark-image-media-queries package instead.

Use different images in light- and dark mode in CommonMark-rendered Markdown

v1.0.0 2023-07-11 12:23 UTC

Requires

• league/commonmark: ^2.3

Requires (Dev)

• ext-dom: *
• phpunit/phpunit: ^10.0
• spatie/phpunit-snapshot-assertions: ^5.0.1

MIT

• Sven Luijten

• markdown
• images
• light
• color scheme
• commonmark
• dark
• darkmode
• prefers-color-scheme

README

⚠️ This package is abandoned. Use sven/commonmark-image-media-queries instead ⚠️

This CommonMark extension allows you to determine what images to show in dark- or light mode in Markdown converted using CommonMark.

Installation

Via composer:

composer require sven/commonmark-dark-mode-images

Usage

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

use Sven\CommonMark\DarkModeImages\DarkModeImagesExtension;

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

You'll have to apply some classes to your Markdown images to indicate to this extension that they should be converted:

![Screenshot of a settings dialog](/images/settings-light.jpg){.light-image}
![dark](/images/settings-dark.jpg){.dark-image}

These {.light-image} and {.dark-image} tags are part of the Attributes extension. They apply classes to the converted <img> elements, which this extension uses to do its magic. The resulting HTML will look something like this:

<picture class="dark-mode-images-picture">
    <source srcset="/images/settings-dark.jpg" media="(prefers-color-scheme: dark)" />
    <img src="/images/settings-light.jpg" alt="Screenshot of a settings dialog"/>
</picture>

And the result in the browser:

Click to reveal

Or check out the first blog post I used this on.

Configuration

Fallback or original

This option allows you to select either 'light' or 'dark' as the "original" form of the picture you're embedding. This determines which picture will be used if the browser doesn't support the <picture> element.

use League\CommonMark\Environment\Environment;
use Sven\CommonMark\DarkModeImages\DarkModeImagesExtension;

$environment = new Environment([
    'dark_mode_images' => [
        'fallback' => 'dark', // Default: 'light'.
    ],
]);

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

Class on <picture> element

To change the class that is eventually applied to the rendered <picture> element, use the picture_class configuration option:

use League\CommonMark\Environment\Environment;
use Sven\CommonMark\DarkModeImages\DarkModeImagesExtension;

$environment = new Environment([
    'dark_mode_images' => [
        'picture_class' => '<your class here>', // Default: 'dark-mode-images-picture'.
    ],
]);

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

Light and dark classes

Use the dark_image_class and light_image_class configuration options to determine what classes to apply to your Markdown images to indicate which is for dark mode, and which is for light mode.

use League\CommonMark\Environment\Environment;
use Sven\CommonMark\DarkModeImages\DarkModeImagesExtension;

$environment = new Environment([
    'dark_mode_images' => [
        'light_image_class' => 'l', // Default: 'light-image'.
        'dark_image_class' => 'd', // Default: 'dark-image'.
    ],
]);

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

Note

It is not recommended to use this extension when converting to Markdown on-the-fly on every request. This is best suited for use in a static site generator like Jigsaw.

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-dark-mode-images is licensed under the MIT License (MIT). Please see the license file for more information.