How to colocate images and Markdown in Astro

As a blog grows, the images referenced in Markdown files can quickly get out of control. A common pattern for managing this is to create a folder for each post that contains an index.md file and any images referenced within.

This is called “asset colocation” in Zola and “leaf bundles” in Hugo.

Until recently, this wasn’t possible using Astro’s otherwise excellent content collections feature. However, with the addition of Astro’s Image Service API, we can achieve a near-identical experience to Zola and Hugo.

.
└── src/
    └── content/
        └── posts/
            ├── post-without-images.md
            └── post-with-images/
                ├── index.md
                ├── image1.png
                └── image2.jpg

Simply make sure you’re using Astro 3.0 or later and start organizing your posts like shown above. You can keep using single Markdown files for posts without images, and an subdirectory with an index.md file for those with images.

In Markdown, reference images using a relative path.

![](./image1.png)

This is slightly different from other static site generators that don’t require relative paths because of how they compile sites. In Astro, you can only include images this way, and you need to explicitly reference them in the post.