Skip to content

Global images directory for Markdown

Widely compatibleRendering:Prerendered: WorksOn-demand: WorksAstro>=5.0.0

To run Markdown images through Astro’s built-in image optimization pipeline, Astro expects relative paths from the .md file (such as ../../assets/images/cat.png). That works for small blogs, but becomes awkward with headless or Git-based CMSs that upload every media file into a single shared folder like src/assets/images/.

Depending on how you want authors and your CMS to reference images, you have three clean ways to point Markdown at a shared image root without losing Astro’s image optimization:

Astro passes Markdown image specifiers through Vite’s module resolver using the .md file as the importer. That means TypeScript path aliases work automatically in Markdown image syntax and in content collection frontmatter validated with image().

Add a path alias in tsconfig.json:

tsconfig.json
{
"extends": "astro/tsconfigs/strict",
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@images/*": ["src/assets/images/*"]
}
}
}

You can now reference images from any nested Markdown directory with the same prefix:

src/content/blog/2026/my-post.md
---
title: My post
cover: "@images/cat.png"
---
![A sleeping cat](@images/cat.png)

Both the body image and the cover frontmatter image resolve to src/assets/images/cat.png and are emitted as optimized /_astro/cat.*.webp assets.

Option 2: Bare filenames with a Vite regex alias

Section titled “Option 2: Bare filenames with a Vite regex alias”

If your CMS or authors expect plain filenames like ![](cat.png) without any prefix, Astro normally treats cat.png as a bare package specifier and fails the build with ImageNotFound.

You can solve this entirely in astro.config.mjs with a regex Vite resolve.alias that maps bare image filenames (containing no /) to your shared images directory:

astro.config.mjs
import { fileURLToPath } from "node:url";
import { defineConfig } from "astro/config";
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`,
},
],
},
},
});

With this alias in place, bare filenames work in both Markdown bodies and frontmatter (cover: cat.png), during both astro dev and astro build:

src/content/blog/2026/my-post.md
---
title: My post
cover: cat.png
---
![A sleeping cat](cat.png)

Because the regular expression only matches specifiers without a slash, existing relative paths (./local.png), root-relative public/ paths (/logo.svg), and path aliases (@images/cat.png) keep working unchanged.

Option 3: Rewrite bare filenames to a remote CDN

Section titled “Option 3: Rewrite bare filenames to a remote CDN”

When images live on an external CDN rather than in src/assets/, Markdown images whose host is listed in image.domains (or image.remotePatterns) are still optimized at build time with their dimensions inferred automatically.

Because user Markdown plugins run before Astro collects images, you can rewrite bare filenames into full CDN URLs in a small Markdown plugin and let Astro’s built-in image pipeline pick them up:

astro.config.mjs
import { satteri } from "@astrojs/markdown-satteri";
import { defineConfig } from "astro/config";
const cdnPrefix = (base) => ({
name: "cdn-prefix",
image(node, ctx) {
if (/^[\w-][\w.-]*\.\w+$/.test(node.url)) {
ctx.setField(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/")],
}),
},
});

Compatibility

EnvironmentSupportVersion
Framework
AstroWorks>=5.0.0
RenderingAstro docs
PrerenderedWorksAny version
On-demandWorksAny version
Compatibility legend:Recommended — Best practiceWorks — SupportedDoesn't work — Unsupported