I’ve been writing articles in Markdown files using Gatsby.js, and I’ve summarized how to automatically build and compress images (.png and .jpg) within articles into WebP format.

Implementation Method (Conclusion)

Use gatsby-remark-images.

Documentation

Installing Plugins via Command

Install the necessary plugins.

If you started your Gatsby.js project using a starter, many of these plugins might already be installed.

npm install gatsby-remark-images gatsby-plugin-sharp gatsby-transformer-remark

Modify gatsby.config.js

These plugins may already be included, so check carefully to avoid duplication by searching for the relevant text.

plugins: [
  `gatsby-plugin-sharp`,
  {
    resolve: `gatsby-transformer-remark`, // It’s likely already written
    options: {
      plugins: [
        // There might be other plugins here
        {
          resolve: `gatsby-remark-images`,
          options: {
            maxWidth: 630,
            showCaptions: false,
            withWebp: true, // Converts images to WebP
            withAvif: true, // Converts images to Avif
          },
        },
      ],
    },
  },
]

For more details on the options of this plugin, refer to the following article:

How to Use gatsby-remark-images

Verify That the Image Directory is Defined in Filesystems

In this case, I added the following configuration:

gatsby.config.js

{
    resolve: `gatsby-source-filesystem`,
    options: {
        name: `content-images`,
        path: `${__dirname}/content/images`,
    },
},

Referencing Images from Markdown Files Using Relative Paths

I tried several methods, but absolute paths didn’t work well, so I used relative paths instead.

Even though using ../ feels a bit awkward, I settled on this approach.

├── content
│    ├── blog
     │    └── slug
     │         └── ja.md //記事ファイル
     └── images
           └── sample.png

When referencing the image from the article file:

![](../../images/sample.png)

In my case, I arrived at this directory structure because I wanted to use the same image across multiple articles, but the method described below also works.

Patterns That Didn’t Work

1. The image was placed in a location not defined in filesystems.
2. The path was not written as a relative path.
3. The cache was not generated.

When the Cache Wasn’t Generated Properly

After copying the entire image folder, the image cache wasn’t generated, so I stopped the local server, deleted the contents of both the .cache directory and the public directory, and restarted the local server, which successfully generated the cache.

gatsby develop

Conclusion

That’s it.

In the end, it was a simple task.

I’m glad I was able to improve the image loading speed, and I feel like I’ve deepened my understanding of the process, so that’s a plus!

If anyone knows a method for using absolute paths, please let me know—I’m still feeling a bit unsure about it.

Actually, through this task, I learned about the Avif compression format for the first time.

For me, WebP was the latest format, so I’m struggling to keep up with technological progress.

I hope this helps someone.