Global images directory for Markdown
Widely compatibleRendering:Prerendered: WorksOn-demand: WorksAstro>=5.0.0
Works across all listed Astro environments.
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:
- Import aliases (
@images/cat.png) — simplest setup, works in both Markdown bodies and frontmatterimage()fields. - Vite regex alias (
cat.png) — lets authors write bare filenames with no prefix at all. - CDN rewrite plugin — maps bare filenames to a remote image host while still optimizing and inferring dimensions.
Option 1: TypeScript import aliases
Section titled “Option 1: TypeScript import aliases”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:
{ "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:
---title: My postcover: "@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  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:
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:
---title: My postcover: 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:
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/")], }), },});Install @astrojs/markdown-remark and unist-util-visit:
npm i @astrojs/markdown-remark unist-util-visitpnpm add @astrojs/markdown-remark unist-util-visityarn add @astrojs/markdown-remark unist-util-visitbun add @astrojs/markdown-remark unist-util-visitdeno add @astrojs/markdown-remark unist-util-visitimport { unified } from "@astrojs/markdown-remark";import { defineConfig } from "astro/config";import { visit } from "unist-util-visit";
function remarkCdnPrefix(base) { return () => (tree) => { visit(tree, "image", (node) => { if (/^[\w-][\w.-]*\.\w+$/.test(node.url)) { node.url = new URL(node.url, base).href; } }); };}
export default defineConfig({ image: { domains: ["cdn.example.com"], }, markdown: { processor: unified({ remarkPlugins: [remarkCdnPrefix("https://cdn.example.com/images/")], }), },});Install unist-util-visit:
npm i unist-util-visitpnpm add unist-util-visityarn add unist-util-visitbun add unist-util-visitdeno add unist-util-visitimport { defineConfig } from "astro/config";import { visit } from "unist-util-visit";
function remarkCdnPrefix(base) { return () => (tree) => { visit(tree, "image", (node) => { if (/^[\w-][\w.-]*\.\w+$/.test(node.url)) { node.url = new URL(node.url, base).href; } }); };}
export default defineConfig({ image: { domains: ["cdn.example.com"], }, markdown: { remarkPlugins: [remarkCdnPrefix("https://cdn.example.com/images/")], },});Source discussion
Section titled “Source discussion”Compatibility
| Environment | Support | Version |
|---|---|---|
| Framework | ||
| Astro | Works | >=5.0.0 |
| RenderingAstro docs | ||
| Prerendered | Works | Any version |
| On-demand | Works | Any version |