diff --git a/docs/configuration.md b/docs/configuration.md index c011af891..4b831b897 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -57,13 +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. If this 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](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. - - ![[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._ +- `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. ## Plugins diff --git a/docs/plugins/Assets.md b/docs/plugins/Assets.md index 98602f0b0..aaa5975a1 100644 --- a/docs/plugins/Assets.md +++ b/docs/plugins/Assets.md @@ -4,7 +4,7 @@ tags: - plugin/emitter --- -This plugin emits all non-Markdown static assets in your content folder (like images, videos, HTML, etc). The plugin respects the `ignorePatterns` and `optimizeImages` in the global [[configuration]]. +This plugin emits all non-Markdown static assets in your content folder (like images, videos, HTML, etc). The plugin respects the `ignorePatterns` and `optimizeImages` configurations in [[configuration#General-Configuration|General Configuration]]. Note that all static assets will then be accessible through its path on your generated site, i.e: `host.me/path/to/static.pdf` diff --git a/docs/plugins/CustomOgImages.md b/docs/plugins/CustomOgImages.md index 4b5bf0391..c0a585dee 100644 --- a/docs/plugins/CustomOgImages.md +++ b/docs/plugins/CustomOgImages.md @@ -64,6 +64,8 @@ The following properties can be used to customize your link previews: The `socialImage` property should contain a link to an image either relative to `quartz/static`, or a full URL. If you have a folder for all your images in `quartz/static/my-images`, an example for `socialImage` could be `"my-images/cover.png"`. Alternatively, you can use a fully qualified URL like `"https://example.com/cover.png"`. +The `socialImage` link respects the `optimizeImages` configuration in [[configuration#General-Configuration|General Configuration]] and is automatically rewritten if web image optimization is turned on. + > [!info] Info > > The priority for what image will be used for the cover image looks like the following: `frontmatter property > generated image (if enabled) > default image`. diff --git a/docs/plugins/Images.md b/docs/plugins/Images.md new file mode 100644 index 000000000..0552c9e26 --- /dev/null +++ b/docs/plugins/Images.md @@ -0,0 +1,68 @@ +--- +title: Images +tags: + - plugin/transformer +--- + +> [!note] +> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page. + +> [!warning] +> Removing this plugin is _not_ recommended. Use [[configuration#General-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|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](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._ + + +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. Here are a few things you could do: + +- Make image optimization 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. +> +> An example supported image tag with custom dimensions: +> +> ```html +> +> ``` + +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 + +This plugin accepts the following configuration options: + +- `openLinksInNewTab`: (Dependent on [[Images#web-image-optimization|Web Image Optimization]]) If `true`, clicking on a preview image opens the originally sized optimized image in a new tab. Defaults to `false`. + +## API + +- Category: Transformer +- Function name: `Plugin.Images()`. +- Source: [`quartz/plugins/transformers/images.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/images.ts).