Overrides the generation of img tags with Docusaurus

While searching for good tips & tricks about Docusaurus when the number of articles become important, I read that we need to pay attention to lazy load images and, indeed, by default all images are loaded when a blog post is first accessed.

In this article, we'll see how easily we can intercept the creation of the <img> tag when the Markdown content is converted to HTML.

This conversion occurs at two places: when you're surfing on your website or when you're generating a static version of it.

To do this, in fact, we don't need to create a component! We just need to add some lines of code in the src/theme/MDXComponents.js file. If you need more than a couple of extra attributes — a wrapper div, custom CSS, a zoom effect — then a real component is the way to go; that's the subject of Change how Docusaurus will create img tags.

If you don't have that file yet, just create it.

import React from "react";

import MDXComponents from "@theme-original/MDXComponents";
// [...]

export default {
  // Reusing the default mapping
  ...MDXComponents,?
  // highlight-start
  img: (props) => {?
    const { loading, decoding, className, style, height, width, ...rest } = props;?

    return (
      <img
        {...rest}
        // Make sure to keep "height='auto'" (so also disable width) as generated by Docusaurus
        // We shouldn't display the image at full size
        height='auto'
        width=''
        loading={loading || 'lazy'}?
        decoding={decoding || 'async'}?
        className={`${className || ''}`}?

        // Example of how adding extra CSS
        style={{
          border: '20px solid #ccc',
          borderRadius: '6px',
          ...style,?
        }}
      />
    );
  },
  // highlight-end
  // [...]
};

Once added to your MDXComponents.js file, just return to the browser; open any post and refresh the page. You'll see that images have now the loading="lazy" attribute (you can verify using the dev tools panel of your browser). If like in the example given here above, you've added some CSS style; you'll see it immediately.

Easy no?

Now, how do you make sure it stays true across two hundred articles? By checking it automatically: see Running some checks on your Docusaurus images.