Nicer Image URLs with eleventy-plugin-remark and remark-images

This weekend I fixed how my blog saves generated images, which bothered me (and only me) for a long time. Images are now stored in the same folder as the HTML file that embeds them, for example, the post My Favourite Albums of 2021 and its images are now all stored in /blog/favourite-albums-2021/. Previously the images were stored in /blog/2022-01-05-favourite-albums-2021/, because the source (Markdown post and original images) where stored in that folder and the permalink option from Eleventy would only rewrite the URL of the HTML file, but not of the images included.

I was able to make the URLs nicer by two features that I have recently added to the libraries involved in this process:

I now pass metadata from Eleventy to the remark library in @fec/eleventy-plugin-remark. The data includes the Eleventy environment data, global data, and page data. Remark plugins can access this data and therefore use metadata when processing Markdown.
I added an option to @fec/remark-images that can transform the file name of the target images. The option expects a function that receives the file name and the context data.

None of this was particularly hard to implement, but it took me a long time to figure out the best way to implement this. I didn't want this feature to only work with Eleventy, but it should be useful independent of the context remark is used.

For this blog, I used the following config to transform the image file names:

eleventyConfig.addPlugin(eleventyRemark, {
  enableRehype: false,
  plugins: [
    {
      plugin: require('@fec/remark-images'),
      options: {
        srcDir: path.join(__dirname, 'site'),
        targetDir: path.join(__dirname, 'dist'),
        transformTargetFileName: (fileName, data) =>
          `${data.eleventy.page.url}${path.basename(fileName)}`,
        //other remark-images options...
      },
    },
    // other remark plugins...
  ],
});

If you are curious, here are links to the two libraries: