#78 Support lazy loading for image and figure

[Tim Hoffmann]

Lazy loading can be achieved by adding a loading attribute to the <img> tag in HTML <img ... loading="lazy">.

https://html.spec.whatwg.org/multipage/urls-and-fetching.html#lazy-loading-attributes

The ReST code should probably look like this:

.. image:: test.png
   :loading: lazy

and

.. figure:: test.png
   :loading: lazy

[engelbert gruber]

responsive images and lazy loading
https://sourceforge.net/p/docutils/mailman/docutils-develop/thread/a461cd5a-6222-45bc-ac66-0be0117e6002%40Spark/#msg37264494

different syntax for responsive images
https://github.com/sphinx-doc/sphinx/issues/9147

[Günter Milde]

Thank you for the suggestion to improve Docutils.

A new directive option and element attribute would require a change to the rst specification (https://docutils.sourceforge.io/docs/ref/rst/directives.html)
and the Docutils DTD https://docutils.sourceforge.io/docs/ref/doctree.html .
For the "lazy loading", it may be simpler to rely on a "magic"
class attribute value:
the HTML5 writer (or a variant of) could add loading="lazy" for image directives like::

.. image:: my-big-example.png
        :alt: large bitmap image
        :class: lazy

Class attributes in Docutils are used to carry optional information
to the writer and not only passed to the output format (the HTML5 writer, e.g., uses the tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>, <code>, ...
if a matching class value is found in inline, literal-block and literal elements and will use <summary> and <details> for term and definition of a definition list with class value "details" in Docutils 0.18).

However, the class attribute "should not be used to carry formatting instructions or arbitrary content." (https://docutils.sourceforge.io/docs/ref/doctree.html#classes) .

Would the attached patch (against Docutils 0.17) help?

Things to consider:

• Do we really want to add this considering the privacy issues mentioned in https://html.spec.whatwg.org/multipage/urls-and-fetching.html#lazy-loading-attributes?

• Use a "class" value or a dedicated attribute? If using a "magic" class value, which: "lazy", "lazy-loading", "load-lazy", "loading-lazy", ...,?

• A full patch would need a test case in test_writers/test_html5_polyglot_misc.py and documentation.

[Tim Hoffmann]

Thanks for the feedback! I don't have time to look into the proposal right now but will come back later.

Preliminary considerations:

• Privacy issues: While lazy loading could be used for tracking, it's not a privacy risk per-se. Tracking would takes additional actions by the page creator. I suppose someone designing tracking would rarely base that page on docutils, and if so, they still can quite easily inject the attributes by post-processing the html.
• A magic class that turns into an attribute feels a bit like monkey-patching.

[Günter Milde]

Another idea is to merge this with the option to specify image embedding
(cf. https://sourceforge.net/p/docutils/feature-requests/40/ and commit 8581)
using a new "image-loading" config setting and "loading" image directive option:

loading: "lazy", "eager", or "embed"

Suggest at which point an image should be loaded.
Overrides the image-loading configuration setting for this image.

The default value and actual behaviour depend on the writer/output
format.

• HTML:
  embed: If the image can be read from the local file system, it is
  base64_ encoded and included as a data URI_.
  eager: This is the HTML default behaviour: load image source immediately.
  lazy: Specify the lazy loading attribute for this image
  (HTML5 only).

• LaTeX:
  Ignored. Images cannot be embedded in the *.tex
  source and are always embedded in LaTeX-generated document.

• ODF/ODT:
  Currently ignored. Images are embedded by default.

(New in Docutils 0.18.)

OTOH, according to the MDN, "lazy" loading is still "an experimental API that should not be used in production code". Maybe it is better to wait a bit before making Docutils more complicated for a rather special need.
For the time beeing, a magic class value (while not clean when used by Docutils itself) may serve as a simple interface to a custom HTML writer without making the source incompatible to standard rST processors.

[Günter Milde]

The applied patch implements the "image-loading" configuration setting.
A directive option may follow later if required.

[Günter Milde]

Implemented in r8853.
Thank you for the suggestion.

[Günter Milde]

Implemented in Docutils 0.18.
Thanks again for the suggestion.

[Günter Milde]

See [feature-requests:#40] for discussion and patch of a matching "loading" option for the "image" directive to configure the behaviour for individual images.