This post provides a brief guide on how to organize and use images in the Astro AntfuStyle Theme.
Supported Cases for Image Processing#
Astro supports processing images during the build phase via the Image Service API ( is the sharpdefault service), allowing actions like converting to webp, compressing, adding attributes, inferring dimensions to prevent CLS, lazy loading, and async decoding. However, this only applies in the following cases:
- Images stored in
src/
(Images in thepublic/
folder won’t be processed) - Authorized remote images (Note: external images referenced in Markdown using
![]()
will not be processed)
Images in Markdown Files#
It is recommended to store the local images used in the post under the src/assets/
directory, and create a subdirectory based on the post’s filename (e.g., images for src/content/blog/your-post-file-name.md
stored in src/assets/your-post-file-name/
), which will allow them to be optimized during Astro’s build process and make it easier to organize and maintain (this strategy can also apply to other static resources).
# Markdown Post
<!-- Local image stored in `src/assets/post-name/`, it wiil be processed and optimized by Astro, resulting in hashed filenames and output to the `_astro/` directory within `dist` -->
<!-- ✅ Use a relative file path -->
<!-- ✅ Use import alias -->
---
<!-- Image stored in `public/og-images/`, it wiil not be processed and optimized by Astro --><!-- ✅ Use the file path relative to public/ -->
---
<!-- Remote image on another server, it wiil not be processed by Astro --><!-- ✅ Use the full URL of the image -->
---
<!-- ❌ Using <img> tag won't work --><img src="../../assets/post-name/local-image.png" alt="Local image" />
---
<!-- ❌ Using <Image /> component won't work --><Image src="../../assets/post-name/local-image.png" alt="Local image" />
Adjusting Image Attributes in Markdown/MDX
Images in MDX Files#
In addition to supporting the standard Markdown 
syntax as demonstrated above, you can also use Astro’s <Image />
component and JSX <img />
tags in your .mdx
files by importing both the component and your image.
# MDX Post
---title: My Page title---
import { Image } from 'astro:assets';import rocket from '../assets/rocket.png';
// Local image stored in the the same folder
// Local image stored in src/assets/<Image src={rocket} alt="A rocketship in space." /><img src={rocket.src} alt="A rocketship in space." />
// Image stored in public/images/<Image src="/images/stars.png" alt="A starry night sky." /><img src="/images/stars.png" alt="A starry night sky." />
// Remote image on another server<Image src="https://example.com/images/remote-image.png" /><img src="https://example.com/images/remote-image.png" />
Image Compression#
As mentioned, Astro can compress images from the src/
folder. However, for images in blog posts, especially those in public
, it’s recommended to manually compress them to avoid performance issues. Useful tools include , Tinify, and Squoosh. SVGO
Wrapping Up#
I hope this post helps clarify image usage in Markdown/MDX within this theme. For anything not covered here, check out the Astro Images Docs . 📖