Skip to content

Transforming Markdown Images

PicPerf’s Rehype and Remark plugins make it easy to transform and optimize images in Markdown.

Use the PicPerf Rehype plugin to easily transform and optimize Markdown images after they’ve been transformed to HTML.

Run npm install @picperf/rehype.

Wire it up by importing the plugin and configuring it with your Markdown setup. Here’s an example from Astro:

import { rehypePicPerf } from "@picperf/rehype";
export default defineConfig({
markdown: {
rehypePlugins: [rehypePicPerf],
},
// Other stuff...
});

By default, absolute URLs will be prefixed with “https://picperf.io”. If you’d like to disable this behavior for particular URLs, you can use the shouldTransform() option, which should return a boolean. If true, the URL will be transformed (assuming it’s absolute — see more on that below). If false, the URL will be left alone.

markdown:{
rehypePlugins: [[ rehypePicPerf, {
shouldTransform: (url) => {
// Return a boolean based on the URL, or not.
return false;
}
}]],
},

Out of the box, this plugin will not transform image root-relative URLs, like this:

![my image](/my-image.jpg)

In order to transform these, pass a host option. This value will be used alongside the PicPerf host to transform the URL.

markdown:{
rehypePlugins: [[ rehypePicPerf, {
host: "https://macarthur.me"
}]],
},

PicPerf’s Remark plugin is another approach to transforming your Markdown images, particularly before they’ve been transformed into HTML.

Run npm install @picperf/remark.

Import the plugin and configure it. If you’re using Astro, it’d look something like this:

import { remarkPicPerf } from "@picperf/remark";
export default defineConfig({
markdown: {
remarkPlugins: [remarkPicPerf],
},
// Other stuff...
});

Out of the box, URLs will be prefixed with “https://picperf.io”. This behavior can be disabled for particular URLs using the shouldTransform() option — a function that should return a boolean. If true, absolute URLs will be transformed. If false, the URLs will be left unchanged.

markdown:{
remarkPlugins: [[ remarkPicPerf, {
shouldTransform: (url) => {
// Return a boolean based on the URL, or not.
return false;
}
}]],
},

By default, the Remark plugin will not mess with images using root-relative URLs, like this:

![my image](/my-image.jpg)

If you’d like to transform these, pass a host option. The provided value will be used to then transform the URL.

markdown:{
rehypePlugins: [[ rehypePicPerf, {
host: "https://macarthur.me"
}]],
},