Astro 블로그는 처음에는 markdown 파일 몇 개만 넣어도 충분하다.
그런데 글이 늘기 시작하면 가장 먼저 흔들리는 부분은 디자인이 아니다.
의외로 frontmatter다.
title
slug
pubDatetime
tags
category
description이 값들이 조금씩 어긋나면 글은 보이는데 목록이 이상해지고,
검색에는 뜨는데 링크가 마음에 안 들고,
카테고리 페이지에서는 빠지는 일이 생긴다.
frontmatter는 글의 운영 데이터다
markdown 본문은 사람이 읽는 내용이다.
frontmatter는 사이트가 글을 이해하는 데이터다.
예를 들어 글 하나가 이런 값을 가진다고 하자.
title: "Astro 블로그 검색 붙이기"
slug: "astro-pagefind-search-static-blog"
pubDatetime: 2026-05-29T11:15:00+09:00
tags:
- Astro
- Pagefind
category: dev
description: "Astro 정적 블로그에 Pagefind 검색을 붙이는 흐름"이 정보는 여러 곳에서 쓰인다.
- 글 상세 페이지 제목
- 글 목록 정렬
- RSS 피드
- 사이트맵
- 태그 페이지
- 카테고리 페이지
- OG 이미지
- 검색 색인
그래서 frontmatter를 단순 메모처럼 보면 나중에 관리가 어려워진다.
slug는 파일명보다 우선 규칙을 정해두자
Astro에서는 파일 경로를 기반으로 URL을 만들 수도 있고,
frontmatter의 slug를 우선할 수도 있다.
블로그를 오래 운영할 생각이라면 slug를 명시하는 편이 편하다.
slug: "astro-content-collections-frontmatter"파일명은 날짜와 관리용 이름을 담고,
URL은 사람이 공유하기 쉬운 이름으로 유지할 수 있기 때문이다.
파일명:
2026-05-29-astro-content-collections-frontmatter.md
URL:
/posts/astro-content-collections-frontmatter이렇게 분리해두면 나중에 파일 위치를 옮겨도 URL 정책을 유지하기 쉽다.
날짜는 정렬 기준이다
pubDatetime은 화면에 표시되는 날짜이기도 하지만,
대부분의 블로그에서는 최신 글 정렬 기준이기도 하다.
그래서 자동 발행이나 대량 작성 작업을 할 때는 날짜가 더 중요해진다.
자주 생기는 문제는 이렇다.
파일은 오늘 추가
pubDatetime은 예전 날짜
→ 최신 글 목록에 안 보임또는 반대로:
미래 날짜로 들어감
→ 빌드는 되는데 운영상 어색함글을 여러 개 추가할 때는 날짜와 시간을 의도적으로 나눠두는 게 좋다.
tags와 category는 역할을 다르게 봐야 한다
처음에는 둘 다 비슷해 보인다.
하지만 운영하면서는 이렇게 나누는 편이 좋았다.
category = 큰 서랍
tags = 검색 키워드예를 들어 Astro 글이라도 카테고리는 dev로 두고,
태그에 Astro, Pagefind, GitHub Actions를 넣을 수 있다.
그러면 사용자는 큰 흐름으로 dev를 보고,
검색 엔진이나 태그 페이지는 세부 키워드를 따라간다.
description은 꼭 사람이 읽는 문장으로 쓴다
description은 대충 넣기 쉽다.
하지만 이 값은 여러 곳에 재사용된다.
- 검색 결과 요약
- OG meta description
- 글 목록 요약
- RSS 설명
그래서 키워드만 나열하기보다, 한 문장으로 글의 목적을 설명하는 편이 낫다.
나쁜 예:
Astro, frontmatter, slug, tags, category좋은 예:
Astro Content Collections에서 frontmatter를 어떻게 정리해야 글 목록과 카테고리가 덜 꼬이는지 정리한다.schema가 있으면 실수가 빨리 드러난다
Content Collections의 장점은 스키마를 둘 수 있다는 점이다.
예를 들어 pubDatetime이 날짜가 아니거나,
tags가 배열이 아니거나,
필수 description이 빠졌을 때 빌드 단계에서 빨리 알 수 있다.
z.object({
title: z.string(),
slug: z.string().optional(),
pubDatetime: z.date(),
tags: z.array(z.string()).default(["others"]),
description: z.string(),
});글이 적을 때는 귀찮아 보이지만,
자동화가 들어가면 스키마가 안전장치가 된다.
내가 추천하는 최소 frontmatter
기술 블로그라면 최소한 이 정도는 고정하는 편이 좋다.
author: DevBJ
pubDatetime: 2026-05-29T11:10:00+09:00
modDatetime: 2026-05-29T11:10:00+09:00
title: "글 제목"
slug: "stable-url-slug"
featured: false
draft: false
tags:
- Astro
- Tech Blog
category: dev
description: "검색 결과와 글 목록에 표시될 한 문장 설명"여기에 시리즈 글이라면 series, seriesOrder, seriesGroup을 추가하면 된다.
오늘 포인트
Astro Content Collections는 단순히 markdown을 모아두는 기능이 아니다.
글이 많아질수록 frontmatter가 블로그 운영의 기준 데이터가 된다.
처음부터 slug, pubDatetime, tags, category, description의 역할을 나눠두면
나중에 글 목록, 검색, RSS, 사이트맵, 카테고리 페이지가 훨씬 덜 꼬인다.
한 줄 요약
Astro 블로그가 커질수록 본문보다 먼저 frontmatter 규칙을 정리해야 운영이 편해진다.