Specifying global images root directory for Markdown relative-path images

[vadimkantorov]

It can be not CMS-friendly to have a bunch of images directories: content/posts/images/, content/pages/images/ etc

But for full Astro image pipeline processing for Markdown, images in Markdown must be referenced via relative paths.

Is it possible to specify in config path for Markdown images dir root? (and same question for Markdown abspath images - e.g. for the case when images are stored at external image service URL)

---

I can try workarounds with some dir symlinks, but it's not very robust or requires extra build step

[delucis]

Hmm, I’m not sure there’s a fix here. Maybe import aliases? But I’m not sure if those are taken into account for Markdown processing.

[vadimkantorov]

The whole problem is that I don't want to force users to always use ../ prefix to refer to images. Ideally I'd just like to have the image file name only

[AZapata27]

Import aliases do work, for both Markdown body images and image() in frontmatter. Astro hands the src to Vite's resolver with the .md file as the importer, so a tsconfig paths entry like "@images/*": ["./src/assets/images/*"] lets you write ![](@images/cat.png) and get an optimized /_astro/cat.*.webp. Tested on Astro 7.3.8.

If you want just cat.png, you can do it in config alone with a regex Vite alias that maps any bare name.ext to your images folder. Right now a bare cat.png is treated as a package import and the build fails with ImageNotFound. With the alias it resolves, both in the body and in frontmatter (cover: cat.png), in dev and in build:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { fileURLToPath } from 'node:url';

const imagesDir = fileURLToPath(new URL('./src/assets/images/', import.meta.url));

export default defineConfig({
  vite: {
    resolve: {
      alias: [
        { find: /^([\w-][\w.-]*\.(?:png|jpe?g|webp|avif|gif|svg))$/i, replacement: imagesDir + '$1' },
      ],
    },
  },
});

The regex only matches specifiers without a slash, so ./local.png and @images/... keep working.

Remote images: Markdown images on hosts listed in image.domains (or remotePatterns) get optimized, with their size inferred at build time. Anything else is left as a plain <img>. To keep writing bare names but serve them from a CDN, rewrite the URL in a Markdown plugin. Plugins run before Astro collects the images, so the rewritten URL gets picked up. With the default Sätteri processor in Astro 7:

import { satteri } from '@astrojs/markdown-satteri';

const cdnPrefix = (base) => ({
  name: 'cdn-prefix',
  image(node, ctx) {
    if (/^[\w-][\w.-]*\.\w+$/.test(node.url)) ctx.setProperty(node, 'url', new URL(node.url, base).href);
  },
});

export default defineConfig({
  image: { domains: ['cdn.example.com'] },
  markdown: { processor: satteri({ mdastPlugins: [cdnPrefix('https://cdn.example.com/images/')] }) },
});

A remark plugin (unified({ remarkPlugins }) from @astrojs/markdown-remark) works the same way if you're still on remark. Unlike the alias, it only rewrites body images, not frontmatter.