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.

Article Created Updated

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 .md file and an img/ 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, .mdx files vanish from a glob loader without an error. Stay with .md unless 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]

More on this

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

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.

Show in the graph view