Photo Albums with Astro's Content Layer
Album pages on top of the photo stream of my old site: a content collection per album, covers by filename, album-scoped photo routes and a sub-nav.
Reviewed by adrian
on
For a while the photo section of my old site had one view: the chronological stream of every image from every place. That works as a photostream, but it makes a single trip hard to follow. I wanted album pages on top of the stream without rebuilding the stream.
The setup
- Astro 6 with the content layer, without
@astrojs/mdx. - Albums under
src/content/photos/albums/<album>/, each with an.mdfile and animg/folder of JPGs and their JSON sidecars from the vision model. - The stream at
/photos, rendering all sidecars in one justified grid. This change left it alone.
One folder per album
src/content/photos/albums/
chiang-mai/
chiang-mai.md ← metadata + editorial text
img/
2025-10-06-121017.jpg
2025-10-06-121017.json ← Vision sidecar
...
phuket/
phuket.md
img/
...
The .md files form a content collection called photos in content.config.ts:
const photos = defineCollection({
loader: glob({
pattern: "**/*.{md,mdx}",
base: "./src/content/photos/albums",
}),
schema: z.object({
title: z.string(),
description: z.string(),
location: z.string().optional(),
publishDate: z.coerce.date().optional(),
draft: z.boolean().default(false),
}),
});
The files must be .md, not .mdx. Without @astrojs/mdx the glob loader has no handler for .mdx and skips those files silently. The collection stays empty, and the only hint is [WARN] No entry type found in the server log. That cost me about twenty minutes in front of a blank listing page.
Routes
| Route | File |
|---|---|
/photos/albums |
src/pages/photos/albums/index.astro |
/photos/albums/[album] |
src/pages/photos/albums/[album]/index.astro |
/photos/albums/[album]/[id] |
src/pages/photos/albums/[album]/[id].astro |
The photo page at [album]/[id] keeps the reader inside the album. Previous and next step through that album's photos only, sorted by date, and the link in the middle of the pagination bar leads back to the album grid.
Covers for the listing page
The listing page needs a cover per album, but the album's .md file has none, and I did not want to pick covers by hand in the frontmatter. So the page reads all entries of photos that are not drafts and takes the first image from each album folder:
const imageModules = import.meta.glob<{ default: ImageMetadata }>(
"/src/content/photos/albums/**/*.jpg",
{ eager: true },
);
const covers = Object.fromEntries(
albums.map((album) => {
const folder = album.id.split("/")[0] ?? album.id;
const cover = Object.entries(imageModules)
.filter(([p]) => p.includes(`/albums/${folder}/`))
.sort(([a], [b]) => a.localeCompare(b))[0];
return [folder, cover?.[1]?.default ?? null];
}),
);
The glob loader gives an album an ID like chiang-mai/chiang-mai, so .split("/")[0] is the folder name. My filenames start with the capture date, so sorting by filename makes the earliest photo of the trip the cover.
The album page
The album page renders the Markdown body of the .md file next to the photo grid. In the content layer render() is a function imported from astro:content, no longer a method on the entry:
import { getCollection, render } from "astro:content";
const { Content } = await render(album);
The photos load with import.meta.glob, filtered to the album's folder and sorted by date. Each one links to its route inside the album:
<a href={`/photos/albums/${folder}/${photo.sidecar.id}`}>
The grid is the same as in the stream: justified-layout with a target row height of 280px, positioned absolutely inside a container whose height comes from the layout result.
A sub-nav between stream and albums
/photos and /photos/albums share a small sub-nav. The active link is set by hand on each page:
<!-- on /photos -->
<a href="/photos" class="sub-nav__link is-active">Stream</a>
<a href="/photos/albums" class="sub-nav__link">Albums</a>
<!-- on /photos/albums -->
<a href="/photos" class="sub-nav__link">Stream</a>
<a href="/photos/albums" class="sub-nav__link is-active">Albums</a>
The stream at /photos and the single photo route /photos/[id] stayed as they were. The albums were an extra layer: the same images on disk, other entry points and another navigation context.
Takeaways
- Without
@astrojs/mdx,.mdxfiles vanish from a glob loader without an error. Stay with.mdunless you need MDX. - With date-prefixed filenames, a cover by filename sort beats a
cover:field you have to maintain. - Album routes on top of a flat stream cost little: the same JPGs and sidecars, only other shapes of
getStaticPaths.
Based on
-
Photo Albums with Astro's Content Layer
(
raw/2026/2026-03-19/photo-albums-with-astro-s-content-layer.md) [post]
Topic
- Static Website A website made of finished HTML files that are built once and then served unchanged. No server code, no database.
Basis for
- Structuring Photos as a Collection Tree How the photos of my old Astro site grew from flat albums into a recursive tree: one catch-all route, photos per node, breadcrumbs and tag pages.
Builds on
- Building the Photo Stream The photo stream of my old Astro site: JSON sidecars next to each JPG, import.meta.glob, a justified grid and batches revealed on scroll.
Uses
- Astro Tool for building websites from content such as Markdown. Ships plain HTML by default and only loads JavaScript where it is needed.