Merge pull request #9447 from quarto-dev/feature/listing-img-lazy

listings - add 'lazy: false' to item to control lazy loading of images

news/changelog-1.5.md

@@ -80,6 +80,7 @@ All changes included in 1.5:
 - ([#8715](https://github.com/quarto-dev/quarto-cli/issues/8715)): Listings should respect `image: false`
 - ([#8860](https://github.com/quarto-dev/quarto-cli/discussions/8860)): Don't show duplicate author names.
 - ([#9030](https://github.com/quarto-dev/quarto-cli/discussions/9030)): Warn (rather than error) when listing globs produce an empty listing (as this is permissable).
+- ([#9447](https://github.com/quarto-dev/quarto-cli/pull/9447)): Add support for the boolean `image-lazy-loading` option to enable lazy loading of images in listings (default: `true`).
 
 ## Manuscripts
 

src/project/types/website/listing/website-listing-read.ts

@@ -62,6 +62,7 @@ import {
   kImageAlign,
   kImageAlt,
   kImageHeight,
+  kImageLazyLoading,
   kImagePlaceholder,
   kInclude,
   kListing,
@@ -117,6 +118,7 @@ import {
   isProjectDraft,
   projectDraftMode,
 } from "../website-utils.ts";
+import { kFieldImageLazyLoading } from "./website-listing-shared.ts";
 
 // Defaults (a card listing that contains everything
 // in the source document's directory)
@@ -1117,6 +1119,9 @@ async function listItemFromFile(
       : undefined;
 
     const imageAlt = documentMeta?.[kImageAlt] as string | undefined;
+    const imageLazyLoading = documentMeta?.[kImageLazyLoading] as
+      | boolean
+      | undefined;
 
     const date = documentMeta?.date
       ? parsePandocDate(resolveDate(input, documentMeta?.date) as string)
@@ -1170,6 +1175,7 @@ async function listItemFromFile(
       [kFieldCategories]: categories,
       [kFieldImage]: image,
       [kFieldImageAlt]: imageAlt,
+      [kFieldImageLazyLoading]: imageLazyLoading,
       [kFieldDescription]: description,
       [kFieldFileName]: filename,
       [kFieldFileModified]: filemodified,

src/project/types/website/listing/website-listing-shared.ts

@@ -73,6 +73,9 @@ export const kImageAlign = "image-align";
 // Alt text for the item's image
 export const kImageAlt = "image-alt";
 
+// Lazy loading for the item's image. If unset, the default is true.
+export const kImageLazyLoading = "image-lazy-loading";
+
 // The placeholder image for the item
 export const kImagePlaceholder = "image-placeholder";
 
@@ -101,6 +104,7 @@ export const kFieldFileModified = "file-modified";
 export const kFieldDate = "date";
 export const kFieldImage = "image";
 export const kFieldImageAlt = "image-alt";
+export const kFieldImageLazyLoading = "image-lazy-loading";
 export const kFieldDescription = "description";
 export const kFieldReadingTime = "reading-time";
 export const kFieldWordCount = "word-count";
@@ -211,6 +215,7 @@ export interface ListingItem extends Record<string, unknown> {
   date?: Date;
   image?: string;
   [kImageAlt]?: string;
+  [kImageLazyLoading]?: boolean;
   path?: string;
   filename?: string;
   [kFieldFileModified]?: Date;

src/project/types/website/listing/website-listing-template.ts

@@ -95,7 +95,7 @@ export function templateMarkdownHandler(
             // For file modified specifically, include the time portion
             const includeTime = field === kFieldFileModified;
 
-            const date = typeof (dateRaw) === "string"
+            const date = typeof dateRaw === "string"
               ? parsePandocDate(dateRaw as string)
               : dateRaw as Date;
             if (date) {
@@ -422,6 +422,7 @@ export function reshapeListing(
     src: string,
     classes: string,
     alt?: string,
+    lazy?: boolean,
   ) => {
     const pageSize = listing[kPageSize];
     const classAttr = classes ? `class="${classes}"` : "";
@@ -430,8 +431,8 @@ export function reshapeListing(
       : "";
     const altAttr = alt ? `alt="${encodeAttributeValue(alt)}"` : "";
     const srcAttr = itemNumber > pageSize ? "data-src" : "src";
-
-    return `<img ${srcAttr}="${src}" ${classAttr} ${styleAttr} ${altAttr}>`;
+    const lazyAttr = lazy === false ? "" : "loading='lazy' ";
+    return `<img ${lazyAttr}${srcAttr}="${src}" ${classAttr} ${styleAttr} ${altAttr}>`;
   };
   utilities.imgPlaceholder = (
     itemNumber: number,

src/resources/editor/tools/vs-code.mjs

@@ -10597,6 +10597,12 @@ var require_yaml_intelligence_resources = __commonJS({
                   description: "The default image to use if an item in the listing doesn't have an image."
                 }
               },
+              "image-lazy-loading": {
+                boolean: {
+                  description: "If false, images in the listing will be loaded immediately. If true, images will be loaded as they come into view.",
+                  default: true
+                }
+              },
               "image-align": {
                 enum: [
                   "left",
@@ -18472,6 +18478,20 @@ var require_yaml_intelligence_resources = __commonJS({
             ]
           },
           description: "The alt text for preview image on this page."
+        },
+        {
+          name: "image-lazy-loading",
+          schema: "boolean",
+          tags: {
+            formats: [
+              "$html-doc"
+            ]
+          },
+          description: {
+            short: "If true, the preview image will only load when it comes into view.",
+            long: 'Enables lazy loading for the preview image. If true, the preview image element \nwill have `loading="lazy"`, and will only load when it comes into view.\n\nIf false, the preview image will load immediately.\n'
+          },
+          default: true
         }
       ],
       "schema/extension.yml": [
@@ -21151,6 +21171,7 @@ var require_yaml_intelligence_resources = __commonJS({
         "The name to display in the UI.",
         "The name of the language the kernel implements.",
         "The name of the kernel.",
+        "Configures the Julia engine.",
         "Arguments to pass to the Julia worker process.",
         "Environment variables to pass to the Julia worker process.",
         "Set Knitr options.",
@@ -22744,7 +22765,11 @@ var require_yaml_intelligence_resources = __commonJS({
         },
         "Disambiguating year suffix in author-date styles (e.g. \u201Ca\u201D in \u201CDoe,\n1999a\u201D).",
         "Manuscript configuration",
-        "internal-schema-hack"
+        "internal-schema-hack",
+        {
+          short: "If true, the preview image will only load when it comes into\nview.",
+          long: 'Enables lazy loading for the preview image. If true, the preview\nimage element will have <code>loading="lazy"</code>, and will only load\nwhen it comes into view.\nIf false, the preview image will load immediately.'
+        }
       ],
       "schema/external-schemas.yml": [
         {
@@ -22973,12 +22998,12 @@ var require_yaml_intelligence_resources = __commonJS({
         mermaid: "%%"
       },
       "handlers/mermaid/schema.yml": {
-        _internalId: 183687,
+        _internalId: 186197,
         type: "object",
         description: "be an object",
         properties: {
           "mermaid-format": {
-            _internalId: 183679,
+            _internalId: 186189,
             type: "enum",
             enum: [
               "png",
@@ -22994,7 +23019,7 @@ var require_yaml_intelligence_resources = __commonJS({
             exhaustiveCompletions: true
           },
           theme: {
-            _internalId: 183686,
+            _internalId: 186196,
             type: "anyOf",
             anyOf: [
               {

src/resources/editor/tools/yaml/yaml-intelligence-resources.json

@@ -3569,6 +3569,12 @@
               "description": "The default image to use if an item in the listing doesn't have an image."
             }
           },
+          "image-lazy-loading": {
+            "boolean": {
+              "description": "If false, images in the listing will be loaded immediately. If true, images will be loaded as they come into view.",
+              "default": true
+            }
+          },
           "image-align": {
             "enum": [
               "left",
@@ -11444,6 +11450,20 @@
         ]
       },
       "description": "The alt text for preview image on this page."
+    },
+    {
+      "name": "image-lazy-loading",
+      "schema": "boolean",
+      "tags": {
+        "formats": [
+          "$html-doc"
+        ]
+      },
+      "description": {
+        "short": "If true, the preview image will only load when it comes into view.",
+        "long": "Enables lazy loading for the preview image. If true, the preview image element \nwill have `loading=\"lazy\"`, and will only load when it comes into view.\n\nIf false, the preview image will load immediately.\n"
+      },
+      "default": true
     }
   ],
   "schema/extension.yml": [
@@ -14123,6 +14143,7 @@
     "The name to display in the UI.",
     "The name of the language the kernel implements.",
     "The name of the kernel.",
+    "Configures the Julia engine.",
     "Arguments to pass to the Julia worker process.",
     "Environment variables to pass to the Julia worker process.",
     "Set Knitr options.",
@@ -15716,7 +15737,11 @@
     },
     "Disambiguating year suffix in author-date styles (e.g. “a” in “Doe,\n1999a”).",
     "Manuscript configuration",
-    "internal-schema-hack"
+    "internal-schema-hack",
+    {
+      "short": "If true, the preview image will only load when it comes into\nview.",
+      "long": "Enables lazy loading for the preview image. If true, the preview\nimage element will have <code>loading=\"lazy\"</code>, and will only load\nwhen it comes into view.\nIf false, the preview image will load immediately."
+    }
   ],
   "schema/external-schemas.yml": [
     {
@@ -15945,12 +15970,12 @@
     "mermaid": "%%"
   },
   "handlers/mermaid/schema.yml": {
-    "_internalId": 183687,
+    "_internalId": 186197,
     "type": "object",
     "description": "be an object",
     "properties": {
       "mermaid-format": {
-        "_internalId": 183679,
+        "_internalId": 186189,
         "type": "enum",
         "enum": [
           "png",
@@ -15966,7 +15991,7 @@
         "exhaustiveCompletions": true
       },
       "theme": {
-        "_internalId": 183686,
+        "_internalId": 186196,
         "type": "anyOf",
         "anyOf": [
           {

src/resources/projects/website/listing/item-default.ejs.md

@@ -41,7 +41,7 @@ print(`<div class="metadata-value listing-${field}">${listing.utilities.outputLi
 <div class="thumbnail">
 <a href="<%- item.path %>" class="no-external">
 <% if (item.image) { %>
-<%= listing.utilities.img(itemNumber, item.image, "thumbnail-image", item['image-alt']) %>
+<%= listing.utilities.img(itemNumber, item.image, "thumbnail-image", item['image-alt'], item['image-lazy-loading'] ?? listing['image-lazy-loading']) %>
 <% } else { %>
 <%= listing.utilities.imgPlaceholder(itemNumber, item.outputHref) %>
 <% } %>

src/resources/projects/website/listing/item-grid.ejs.md

@@ -46,7 +46,7 @@ return !["title", "image", "image-alt", "date", "author", "subtitle", "descripti
 <% if (item.image) { %>
 
 <p class="card-img-top">
-<%= listing.utilities.img(itemNumber, item.image, "thumbnail-image card-img", item['image-alt']) %>
+<%= listing.utilities.img(itemNumber, item.image, "thumbnail-image card-img", item['image-alt'], item['image-lazy-loading'] ?? listing['image-lazy-loading']) %>
 </p>
 <% } else { %>
 <%= listing.utilities.imgPlaceholder(itemNumber, item.outputHref) %>

src/resources/projects/website/listing/listing-table.ejs.md

@@ -55,7 +55,7 @@ let value = readField(item, field);
 
 if (field === "image") {
 if (item.image) {
-value = listing.utilities.img(itemNumber, item[field], "", item['image-alt']);
+value = listing.utilities.img(itemNumber, item[field], "", item['image-alt'], item['image-lazy-loading'] ?? listing['image-lazy-loading']);
 } else {
 value = listing.utilities.imgPlaceholder(itemNumber, item.outputHref);
 }

src/resources/schema/definitions.yml

@@ -1579,6 +1579,10 @@
       image-placeholder:
         string:
           description: "The default image to use if an item in the listing doesn't have an image."
+      image-lazy-loading:
+        boolean:
+          description: "If false, images in the listing will be loaded immediately. If true, images will be loaded as they come into view."
+          default: true
       image-align:
         enum: [left, right]
         description: In `default` type listings, whether to place the image on the right or left side of the post content (`left` or `right`).

src/resources/schema/document-website.yml

@@ -62,3 +62,16 @@
   tags:
     formats: [$html-doc]
   description: The alt text for preview image on this page.
+
+- name: image-lazy-loading
+  schema: boolean
+  tags:
+    formats: [$html-doc]
+  description:
+    short: If true, the preview image will only load when it comes into view.
+    long: |
+      Enables lazy loading for the preview image. If true, the preview image element 
+      will have `loading="lazy"`, and will only load when it comes into view.
+
+      If false, the preview image will load immediately.
+  default: true

src/resources/types/schema-types.ts

@@ -797,6 +797,8 @@ Learn more about supported date formatting values [here](https://deno.land/std@0
 Defaults to 175. */;
   "image-placeholder"?:
     string /* The default image to use if an item in the listing doesn't have an image. */;
+  "image-lazy-loading"?:
+    boolean /* If false, images in the listing will be loaded immediately. If true, images will be loaded as they come into view. */;
   "image-align"?:
     | "left"
     | "right" /* In `default` type listings, whether to place the image on the right or left side of the post content (`left` or `right`). */;

tests/docs/smoke-all/listings/image-lazy-loading/.gitignore

@@ -0,0 +1 @@
+/.quarto/