GitHub/quartz
1
0
Fork 2
mirror of https://github.com/jackyzha0/quartz.git synced 2025-12-24 13:24:05 -06:00
Code Issues Actions Packages Projects Releases Wiki Activity
13b0fd3055
quartz/docs/plugins/Images.md
Stephen Tse 13b0fd3055 Updated Images doc to mention sharp
2025-05-04 16:52:04 -07:00

3.7 KiB
Raw Blame History

title tags
Images
plugin/transformer

Note

For information on how to add, remove or configure plugins, see the configuration#Plugins page.

Warning

Removing this plugin is not recommended. Use configuration#General-Configuration to turn web image optimization on or off.

This plugin parses and rewrites HTML image tags to support image related features. It's currently associated with the following features:

Web Image Optimization

When optimizeImages in configuration#General-Configuration is set to true:

  • JPEG and PNG images will be stripped all metadata and converted to WebP format, and associated image links in wikilinks will be updated with the new file extension.

  • A resized preview image will replace every local image that have custom dimensions defined either in their wikilink or tag. The original image (optimized or not) will still be assessable as a link on the preview image.

[!note]+ Example usage

The following markdown:

![[images/engelbart.jpeg | 200]]<br/>
_An example optimized preview image of [Douglas Engelbart](https://awards.acm.org/award_winners/engelbart_5078811). Clicking on it opens an originally sized optimized image._

generates the following HTML:

!images/engelbart.jpeg
An example optimized preview image of Douglas Engelbart. Clicking on it opens an originally sized optimized image.

If an image has custom dimensions set, this plugin registers corresponding preview image spec with the Assets emitter so that the latter generates an additional preview image that matches the aspect ratio but with a small resolution bump. Note that Assets never upscales an image, so preview image file sizes are never larger than the originally sized optimized images.

Update the Assets emitter source code if you want to tweak the image format conversion or/and resizing logic with sharp. Here are a couple things you could do following code comments:

  • Make sharp emit AVIF images instead, which is considered a mainstream successor to the WebP format, has better compression ratio and image feature sets (such as HDR support), but currently has narrower browser support and may be slower in image processing.

  • Enable optimization for animated GIF / GIFV images. Note that animated image processing can be very slow, only use it after testing!

Warning

If you use image tags with custom dimensions directly in your markdown documents, remember to manually add a data-slug property with the paths of the image file, otherwise the Assets emitter won't know which file path to emit the preview image to.

An example supported image tag with custom dimensions:

<img href="../../assets/abc.jpg" width="100" data-slug="assets/abc.jpg" />

The logic to use optimized images in CustomOgImages is separately implemented in the ogImage emitter, but is fully transparent to end users.

Configuration options

This plugin accepts the following configuration options:

  • openLinksInNewTab: (Dependent on Images#web-image-optimization) If true, clicking on a preview image opens the originally sized optimized image in a new tab. Defaults to false.

API