Nuxt Content에서 YAML Frontmatter와 Slug의 역할 정리

1. YAML Frontmatter란?

Markdown 파일 상단에 사용하는 --- 사이의 영역으로, 글의 메타데이터(metadata) 를 담는 곳이다.

---
title: GPT 가이드
slug: gpt-guide
description: ChatGPT를 활용한 글쓰기 전략
category: ai
tags: [chatgpt, prompt, ai]
---

이 영역은 Nuxt Content에서 자동으로 파싱되어 JavaScript 객체처럼 사용된다.

예시 결과:

{
  title: 'GPT 가이드',
  slug: 'gpt-guide',
  description: 'ChatGPT를 활용한 글쓰기 전략',
  category: 'ai',
  tags: ['chatgpt', 'prompt', 'ai'],
  body: { ...Markdown 내용... },
  _path: '/blog/ko/gpt-guide'
}

2. title vs # 제목

구분	역할
`title`	글의 제목 (목록, SEO, 메타데이터에 사용됨)
`# 제목`	본문 내에서 시각적 구조를 위한 Markdown 헤더 (h1, h2 등)

즉, title은 시스템이 이해하는 데이터이고, # 제목은 사용자가 보는 본문 시각 구조이다.

두 값이 같을 수도 있지만, 기능은 다르다.

3. slug란?

slug는 글의 고유 URL 경로 마지막 부분이다. 보통 영문 소문자로 구성하며 띄어쓰기는 하이픈(-)으로 구분한다.

slug: gpt-guide

→ 최종 URL: /blog/gpt-guide

slug를 명시하지 않으면 Nuxt는 파일 경로 기반으로 _path를 자동 생성한다.

4. slug를 바꾸면 안 되는 이유

slug는 곧 URL이며, SEO에 직접적인 영향을 준다.
한 번 인덱싱된 URL을 바꾸면 검색 순위, 유입 링크, SNS 공유 등 모두 깨질 수 있다.

바꿔야 한다면?

/server/middleware 또는 백엔드에서 301 리디렉션 처리 필요
예전 URL → 새 URL 매핑 테이블을 만들고 관리해야 함

5. 다국어 콘텐츠 관리와 slug

다국어 블로그에서는 언어별로 .md 파일을 분리하고, slug는 동일하게 유지한다.

/content/blog/ko/gpt-guide.md
/content/blog/en/gpt-guide.md

→ 둘 다 slug는 gpt-guide, 다만 title과 본문 내용은 각 언어에 맞게 다르게 작성한다.

6. slug 없이도 URL 매핑 가능한가?

가능하다. 이 경우 Nuxt Content는 _path를 기준으로 URL을 자동 생성한다.

예:

/content/blog/ko/nuxt/intro.md

→ 자동 URL: /blog/ko/nuxt/intro

하지만 주의할 점:

폴더나 파일 이름이 바뀌면 URL도 바뀐다 → SEO 손실 가능성
따라서 slug를 명시적으로 써주는 것이 안전하다.

7. slug 자동화 전략 요약

전략	설명	추천 상황
`_path` 기반 자동 URL	파일 경로 그대로 URL로 사용	구조가 단순한 블로그
`slug` 명시 + fallback 자동 생성	slug가 없으면 파일명/경로에서 추출	확장성 있는 구조
redirect map	이전 slug → 새 slug로 리디렉션 매핑	slug 변경 가능성 있을 때 필수

보너스: slug를 기준으로 자동 URL 만들기

slug를 파일에서 명시하지 않아도 _path나 title을 가공해 slug를 만들 수 있다.

예:

const { data: articles } = await useAsyncData("blog", () =>
  queryContent(`/blog/${locale.value}`)
    .only(["title", "slug", "_path"])
    .map((item) => ({
      ...item,
      slug: item.slug || item._path.split("/").pop(),
    }))
    .find()
);

이렇게 하면 slug가 없어도 경로 기반으로 대체가 가능하다.

정리

title: SEO 및 목록에 표시되는 글 제목 (Frontmatter에 위치)
# 제목: 본문 구조를 위한 헤더 (h1, h2 등)
slug: 고유 URL 경로, 변경 시 SEO 손실 우려 있음
slug는 명시적으로 쓰는 것을 권장하며, 다국어 콘텐츠에서도 동일하게 유지할 것
자동 생성 slug는 가능하지만 URL 안정성을 위해 직접 작성하는 것이 좋음

이 문서는 @mangoyh가 Nuxt로 블로그를 만들며 실제로 궁금했던 내용을 기반으로 작성되었습니다. 실전에서 유용한 개념만을 정리했으니, 필요할 때마다 참고하세요!