From f07a43672ddf275dc9e187be5116d526f8a13066 Mon Sep 17 00:00:00 2001 From: Stephen Tse Date: Sun, 4 May 2025 18:42:28 -0700 Subject: [PATCH] Separated "Web Image Optimization" to its own feature page --- docs/configuration.md | 2 +- docs/features/Web Image Optimization.md | 33 +++++++++++++++++++++ docs/plugins/Images.md | 38 ++++++------------------- 3 files changed, 43 insertions(+), 30 deletions(-) create mode 100644 docs/features/Web Image Optimization.md diff --git a/docs/configuration.md b/docs/configuration.md index 4b831b897..f8bfc897b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -57,7 +57,7 @@ This part of the configuration concerns anything that can affect the whole site. - `tertiary`: hover states and visited [[graph view|graph]] nodes - `highlight`: internal link background, highlighted text, [[syntax highlighting|highlighted lines of code]] - `textHighlight`: markdown highlighted text background -- `optimizeImages`: whether to optimize images for web serving when building Quartz. Consider turning it off in local testing to speed up build time. See [[Images]] for more information. +- `optimizeImages`: whether to optimize images for web serving when building Quartz. Consider turning it off in local testing to speed up build time. See [[Web-Image-Optimization|Web Image Optimization]] for more information. ## Plugins diff --git a/docs/features/Web Image Optimization.md b/docs/features/Web Image Optimization.md new file mode 100644 index 000000000..c8c23beaf --- /dev/null +++ b/docs/features/Web Image Optimization.md @@ -0,0 +1,33 @@ +--- +title: Web Image Optimization +tags: + - feature/transformer +--- + +Quartz uses [`sharp`](https://github.com/lovell/sharp) to optimize images for web serving at build time. + +When `optimizeImages` in [[configuration#General-Configuration|General Configuration]] is set to `true`: + +- JPEG and PNG images will be stripped all metadata and converted to [WebP](https://caniuse.com/webp) format, and associated image links in `` tags, [[wikilinks#embeds|Wikilinks]] and [[CustomOgImages#frontmatter-properties|Custom OG Image]] frontmatter config `socialImage` will be updated with the new file extension. + +- A resized preview image will replace every local image that has custom dimensions defined either in its [wikilink](https://help.obsidian.md/syntax#External+images) 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: +> +> ```md +> ![[images/engelbart.jpeg | 200]]
+> _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 | 200]]
+> _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._ + + +## Details + +See documentation for the [[Images#web-image-optimization|Images]] transformer plugin for more information. diff --git a/docs/plugins/Images.md b/docs/plugins/Images.md index 8e001a61d..16bfd5c44 100644 --- a/docs/plugins/Images.md +++ b/docs/plugins/Images.md @@ -14,38 +14,10 @@ This plugin parses and rewrites HTML image tags to support image related feature ## Web Image Optimization -When `optimizeImages` in [[configuration#General-Configuration|General Configuration]] is set to `true`: - -- JPEG and PNG images will be stripped all metadata and converted to [WebP](https://caniuse.com/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](https://help.obsidian.md/syntax#External+images) 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: -> -> ```md -> ![[images/engelbart.jpeg | 200]]
-> _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 | 200]]
-> _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._ - +See [[Web-Image-Optimization|Web Image Optimization]] for feature introduction. 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`](https://github.com/lovell/sharp). Here are a few things you could do following code comments: - -- Make `sharp` generate [WebP images](https://sharp.pixelplumbing.com/api-output/#webp) with lossless or near-lossless compression (may dramatically increase output file sizes). - -- Make `sharp` emit [AVIF](https://caniuse.com/avif) images instead, which is considered a mainstream successor to the [WebP](https://caniuse.com/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 | full slug]] of the image file, otherwise the [[Assets]] emitter won't know which file path to emit the preview image to. > @@ -55,6 +27,14 @@ Update the [[Assets]] emitter source code if you want to tweak the image format > > ``` +Update the [[Assets]] emitter source code if you want to tweak the image format conversion or/and resizing logic with [`sharp`](https://github.com/lovell/sharp). Here are a few things you could do following code comments: + +- Make `sharp` generate [WebP images](https://sharp.pixelplumbing.com/api-output/#webp) with lossless or near-lossless compression (may dramatically increase output file sizes). + +- Make `sharp` emit [AVIF](https://caniuse.com/avif) images instead, which is considered a mainstream successor to the [WebP](https://caniuse.com/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! + The logic to use optimized images in [[CustomOgImages | Custom OG Images]] is separately implemented in the `ogImage` emitter, but is fully transparent to end users. ## Configuration options