---
title: 블로그 연동
description: 블로그 목록/상세 페이지 구현 — 컴포넌트 빠른 경로와 직접 fetch 커스텀 경로
---

# 블로그 연동

두 가지 경로가 있습니다:

- **빠른 경로** — `@roottale/cms-renderer-next`의 RSC 컴포넌트 사용. 데이터
  fetch + 렌더링까지 한 번에.
- **커스텀 경로** — `@roottale/cms-client`로 raw 데이터를 가져와 자체 UI로
  렌더링. 디자인을 완전히 통제할 때.

본문 렌더링은 두 경로 모두 `RootTaleBlogPost`(블록 JSON → React)를 쓰는 것을
권장합니다. 본문 JSON 스키마를 직접 파싱하지 마세요.

## 본문 서식과 재사용 블록

ROOT-ADMIN의 글씨 크기·서식 지우기·줄간격·문단 뒤 간격과 이미지 너비·정렬·사진
설명은 공통 에디터에서 저장합니다. `textStyle.attrs.fontSize`, 문단·제목의
`lineHeight`·`paragraphSpacing`, 이미지의 `displayWidth`·`imageAlign`·`caption`을
`RenderTiptap`과 `RootTaleBlogPost`가 출력합니다. 별도 JSON 렌더러를 만들거나
본문의 `style`을 일괄 제거하면 이 서식이 사라집니다. 크기를 지정하지 않은 기존 글은
사이트 기본 CSS를 계속 따릅니다. 사진 원본 `width`·`height`는 유지합니다.

관리자는 선택한 내용을 **재사용 블록** 메뉴에서 현재 사이트의 공통 블록으로 저장할
수 있습니다. 저장에는 공통 블록 관리 권한이 필요하며, 삽입은 글을 편집할 수 있는
사용자에게 제공됩니다. 삽입한 내용은 독립 복사본이므로 원본 블록을 수정해도 이미
삽입한 글은 바뀌지 않습니다. 기존 글 하단의 공통 블록 배치 규칙과는 별개입니다.

공개 사이트는 아래 패키지를 같은 릴리즈 버전으로 업데이트하고 다시 배포하세요.

```bash
pnpm update @roottale/cms-client @roottale/cms-core @roottale/cms-renderer-next --latest
```

## 빠른 경로 — 컴포넌트

### 목록 페이지

```tsx
// app/blog/page.tsx
import { RootTaleBlogList } from "@roottale/cms-renderer-next/server";

export const revalidate = 1800; // 30분 fallback — 실시간 갱신은 웹훅이 담당

export default function BlogPage() {
  return (
    <RootTaleBlogList
      apiKey={process.env.ROOTTALE_API_KEY!}
      baseUrl={process.env.ROOTTALE_API_BASE}
      limit={20}
      showCategoryFilter
    />
  );
}
```

> **글 링크는 기본값에 맡기세요.** `postHref` 를 주지 않으면 카드·연관 글·빵부스러기의
> 글 링크는 플랫폼이 글마다 저장해 내려주는 정규 공개 경로 `post.path`(ADR-0105)를
> 그대로 쓰고, 없을 때(구 서버·주소 규칙 없는 유형)만 `collections` 규칙 →
> `/blog/{slug}` 순으로 폴백합니다. `postHref={(post) => "/blog/" + post.slug}` 처럼
> 하드코딩하면 관리자가 주소 규칙을 바꿔도 사이트가 옛 주소를 계속 그립니다 —
> 라우트가 정말 고정인 사이트에서만 쓰세요.

> **카테고리 허브 라우트(`/blog/categories/{slug}`)를 구현하세요.**
> `showCategoryFilter` 의 카테고리 칩, `RootTaleBlogCategories`, `RootTaleBlogPost`
> 의 `breadcrumb` 카테고리 세그먼트가 모두 기본적으로 이 경로를 링크합니다
> (`defaultCategoryHref`). **단일 블로그 사이트도 예외가 아닙니다** — 이 라우트가
> 없으면 카테고리 칩·브레드크럼을 클릭했을 때 404 가 됩니다. 공지·블로그처럼
> 섹션을 나눈 사이트는 `{basePath}/categories/{slug}` 패턴(`collections.md`
> "URL이 어떻게 정해지나" 절)을 대신 씁니다. 참조 구현은 예시 코드
> `app/blog/categories/[slug]/page.tsx`(MCP tool `readRootTaleNextjsExampleCode`).

> **공지·블로그를 나눈 사이트(ADR-0060)는 목록을 반드시 섹션으로 스코프하세요.**
> `RootTaleBlogList` 는 기본적으로 **모든 글**을 렌더하므로, 섹션을 나눴는데
> `collection` 을 안 주면 공지 글이 `/blog` 목록에 섞여 나옵니다. 각 목록 페이지에서
> `collection`+`collections` 를 넘겨 그 섹션 글만 보이게 하세요(글 링크도 소속 섹션
> basePath 로 자동 라우팅). 단일 블로그 사이트는 지금처럼 안 줘도 됩니다.
>
> ```tsx
> import { COLLECTIONS } from "@/lib/collections"; // collections.md 참고
> // app/notice/page.tsx
> <RootTaleBlogList apiKey={apiKey} collection="notice" collections={COLLECTIONS} />
> // app/blog/page.tsx
> <RootTaleBlogList apiKey={apiKey} collection="blog" collections={COLLECTIONS} showCategoryFilter />
> ```
>
> **`/blog` 가 선언 섹션이 아니라 "나머지 전부"인 사이트**(증상/질환/치료 같은
> 아카이브 스트림만 선언)는 반대로 `collections`+**`excludeCollections`** 로 어느
> 스트림에도 안 속한 글만 렌더하세요:
>
> ```tsx
> <RootTaleBlogList apiKey={apiKey} collections={ARCHIVE_COLLECTIONS} excludeCollections showCategoryFilter />
> ```
>
> 자세한 내용과 `excludeCollections` 오적용 주의(`blog` 자체가 선언 섹션인 사이트에
> 쓰면 목록이 빈다)는 `collections.md` 참고.

### 상세 페이지

> **주소 규칙은 관리자 콘텐츠 모델(`blog`)의 presentation이 정합니다.** RootTale 표준
> 사이트는 `/blog/{category}/{slug}`(카테고리 허브 `/blog/{category}`)이고, 이 문서의
> 예시는 평면 `/blog/{slug}` 상세 규칙(`detail`)을 쓰는 사이트 기준입니다. 어느 쪽이든
> 글 링크·canonical·사이트맵은 공개 API `path`(`post.path`)를 그대로 읽으면 됩니다 —
> `content-models-and-exposures.md` "목록·피드 규칙도 모델이 소유합니다" 참고. 표준
> 사이트의 라우트 파일 배치는 카테고리 허브 `app/blog/[category]/page.tsx`(카테고리가
> 아니면 옛 글 주소로 보고 정본으로 301) + 글 `app/blog/[category]/[slug]/page.tsx` 입니다.

```tsx
// app/blog/[slug]/page.tsx
import { fetchPost } from "@roottale/cms-client/server";
import { RootTaleBlogPost } from "@roottale/cms-renderer-next/server";
import { notFound } from "next/navigation";

export const revalidate = 1800;

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params; // Next.js 15+ async params
  const post = await fetchPost({
    apiKey: process.env.ROOTTALE_API_KEY!,
    baseUrl: process.env.ROOTTALE_API_BASE,
    slugOrId: slug,
  });
  if (!post) notFound();

  return (
    <RootTaleBlogPost
      apiKey={process.env.ROOTTALE_API_KEY!}
      baseUrl={process.env.ROOTTALE_API_BASE}
      slugOrId={post.id}
      showTableOfContents
      tableOfContentsTitle="목차"
      tocPosition="inline"
      theme={null}
      footerPatternPresentation={null}
      relatedPostsCount={3}
      breadcrumb={{ siteUrl: process.env.NEXT_PUBLIC_SITE_URL }}
    />
  );
}
```

`RootTaleBlogPost`는 기본적으로 글 제목을 `<h1>`으로 출력합니다. CMS에서 검토일과
검토자를 지정한 글은 글 상단 메타 영역에 검토 이력도 자동으로 표시됩니다. 공통 배너나
페이지 전용 헤더에서 같은 제목을 직접 마크업한다면 `showTitle={false}`를
넘기세요. 이 옵션은 CMS 제목만 생략하며 요약·발행일·작성자와 본문은 그대로
렌더합니다.

상세 라우트는 렌더 전에 글을 조회하고, 없으면 Next.js `notFound()`를 호출해야
실제 HTTP 404가 됩니다. `notFoundElement`는 컴포넌트 안의 대체 화면일 뿐 응답
상태를 404로 바꾸지 못합니다.

카테고리가 있으면 H1 위에 링크로 표시됩니다. 메타 줄에는 발행일이 명시되고,
수정일의 달력 날짜가 발행일과 다를 때만 수정일을 따로 표시합니다.

SDK 0.69.0부터 `categoryHref`로 H1 위 카테고리 링크를 별도로 지정할 수 있습니다.
`breadcrumb` 없이도 동작하며, 우선순위는 독립 `categoryHref` →
`breadcrumb.categoryHref` → 기본 `/blog/categories/{slug}`입니다.
브레드크럼 링크도 바꾸려면 `breadcrumb.categoryHref`에 같은 함수를 전달하세요.

```tsx
<RootTaleBlogPost
  apiKey={apiKey}
  slugOrId={post.id}
  categoryHref={(slug) => `/insights/${encodeURIComponent(slug)}`}
/>
```

위 `/insights/{slug}`는 해당 사이트에 실제로 구현한 분류 허브 주소여야 합니다.

공지·일정처럼 블로그가 아닌 컬렉션의 상세 화면에 `RootTaleBlogPost`를 쓸 때는
`categoryHref`를 꼭 지정하세요. 지정하지 않으면 분류 링크가 기본값
`/blog/categories/{slug}`로 나가고, 그 사이트에 해당 블로그 분류가 없으면 404가 됩니다.
분류별 허브가 없는 컬렉션은 목록 주소(예: `() => "/notice"`)로 보냅니다.
0.69.0 이전 SDK에서는 같은 함수를 `breadcrumb.categoryHref`로 넘깁니다. 이때 브레드크럼도
함께 표시됩니다.

편집자가 어드민 "관련 콘텐츠"에서 글을 골라 두면(유형 무관, 최대 10개) `RootTaleBlogPost` 는
`relatedPostsCount` 와 무관하게 **그 글들을 고른 순서대로** 글 하단에 그립니다(발행 글만, 저장된
공개 주소로 링크). 고른 것이 없을 때만 아래 자동 추천이 동작합니다.

`relatedPostsCount`(기본 0=off)를 주면 글 하단에 **같은 카테고리 최근 글**을 N개
`<nav class="rt-cms-related">` 로 노출합니다(현재 글 제외, 발행일 내림차순).
제목은 `relatedPostsTitle`(기본 "관련 글"), 링크는 목록과 동일하게 `postHref`
또는 `collections` 로 라우팅됩니다. 현재 글에 카테고리가 없거나 후보가 없으면
렌더되지 않습니다.

목차 위치는 사이트 코드의 `tocPosition="inline" | "sidebar"`로 정합니다. 명시한
값은 CMS 설정보다 우선하며, 생략한 기존 연동은 CMS의 `tocPosition`을 유지합니다.
관리 주체를 코드로 옮길 때는 현재 화면의 배치 값을 명시하세요. 발행 페이지와
미리보기에는 같은 값을 적용합니다. `theme={null}`은 원격 테마 조회·스타일 주입을
끄고, `footerPatternPresentation={null}`은 공통 블록 디자인을 사이트 CSS에 맡깁니다.
두 prop을 생략한 기존 연동은 원격 테마·공통 블록 디자인을 계속 사용합니다.

목차(ToC) 노출·작성자 카드·발행일 표시는 어드민의 블로그 표시 설정으로도 제어됩니다
(`theme-and-settings.md` 참고). 여러 글에 같은 CTA가 필요하면 공통 블록의
`post_footer` 자리를 쓰세요. 공통 블록으로 아직 옮기지 않은 기존 사이트는
`RootTaleBlogPost`가 레거시 `postCta`를 계속 렌더하며, 공통 블록이 배치되면
레거시 CTA를 생략해 고객 화면에 두 개가 겹치지 않습니다.

#### 목차 블록 (본문 임의 위치)

`showTableOfContents` 는 본문 **상단**에 목차를 자동으로 붙입니다. 글 안의
원하는 위치(예: 인트로 문단 다음)에 목차를 넣고 싶다면, 어드민 에디터에서
슬래시 메뉴 `/목차` 로 **목차 블록**(`roottale/table-of-contents`)을 삽입하세요.
렌더러가 그 위치에 문서의 h2–h4 제목으로 목차(`<nav class="rt-cms-toc">`)를
생성하고 각 제목에 앵커 id 를 부여합니다 — 상단 자동 ToC 와 동일 마크업·클래스라
스타일은 그대로 적용됩니다. 헤딩이 하나도 없으면 아무것도 렌더되지 않습니다.

블록을 본문에 직접 배치할 때는 상단 자동 ToC 와 중복되지 않도록
`showTableOfContents` 를 생략(기본 `false`)하는 것을 권장합니다.

#### 블로그 글 구성 + 공식 출처

어드민 에디터의 슬래시 메뉴 `/블로그 글 구성` 또는 툴바의 **블로그 글 구성**을
누르면 인트로 → 목차 → H2 본문 → 공식 출처 → FAQ 골격이 한 번에 들어갑니다.
저장될 안내 문구는 넣지 않고 실제 작성 칸만 비워 둡니다.

`/공식 출처`는 `references` 블록을 삽입합니다. 학회·정부·연구기관처럼 본문
주장을 직접 뒷받침하는 원문을 불릿 링크로 적으세요. 공개 화면에서는
`<section class="rt-cms-references">`와 보이는 제목으로 렌더됩니다. SEO 점검은
이 블록 안에 외부 원문 링크가 있는지도 확인합니다.

이미지 삽입 시 대체 텍스트를 함께 입력합니다. 에디터와 공개 렌더러 모두 줄바꿈·
과도한 공백을 정리하고 최대 160자로 제한하므로, 이미지 주변 문단이나 캡션 전체를
복사하지 말고 이미지의 핵심 의미만 짧게 적으세요.

#### FAQ 블록 (자주 묻는 질문 + 구조화데이터)

어드민 에디터의 슬래시 메뉴 `/FAQ` 로 **FAQ 블록**(`roottale/faq`)을 삽입하면,
발행 시 `RootTaleBlogPost` / `renderBlogPost` 가 자동으로:

- `<details class="rt-cms-faq-item"><summary class="rt-cms-faq-q">질문</summary>
  <div class="rt-cms-faq-a">답변</div></details>` 아코디언(JS 0)을 그리고,
- 글 단위 **`FAQPage` JSON-LD**(`<script type="application/ld+json">`)를 본문 끝에
  1개 삽입합니다 — 구글 FAQ 리치결과/AI 검색 인용 대상.

별도 연동·키 없이 동작하며, 업그레이드 후 기존 글에 FAQ 블록이 있으면 즉시
반영됩니다. 스타일은 `cms-public.css` 의 `.rt-cms-faq*` 클래스가 테마 토큰
(`--rt-color-*`)을 따르므로 추가 CSS 없이 적용됩니다. 직접 렌더 경로를 쓰는
경우 `@roottale/cms-core` 의 `extractFaqEntries(doc)` / `faqPageJsonLd(entries)`
로 동일한 JSON-LD 를 생성할 수 있습니다.

#### 저자 링크 + 브레드크럼 (avcd 구조)

발행 글에 `author_slug`(작가 아카이브 slug)가 있으면 `RootTaleBlogPost` 가
헤더 메타·저자 카드의 작성자 이름을 자동으로 `<a href="/blog/author/{slug}">`
로 감쌉니다. slug 가 없는 작가는 지금처럼 plain text 로 렌더됩니다. 링크
대상을 바꾸려면 `authorHref`:

작성자 사진은 같은 작성자 원장의 `author_image_position_x/y`를 초점으로 사용합니다.
관리자는 작성자 화면에서 사진과 초점을 함께 바꿀 수 있고, 원형·사각형 같은 모양은
각 사이트의 시멘틱 토큰/CSS가 정합니다. 구 서버처럼 좌표가 없으면 가운데(50/50)를
사용합니다.

```tsx
<RootTaleBlogPost
  apiKey={apiKey}
  slugOrId={slug}
  authorHref={(slug) => `/authors/${slug}`} // 기본 /blog/author/{slug}
/>
```

`breadcrumb` prop(opt-in, 기본 off)을 주면 시각 브레드크럼(홈 › 블로그 ›
카테고리 › 글 제목)을 본문 위에 렌더하고, `siteUrl` 을 함께 주면
`BreadcrumbList` JSON-LD 도 같이 emit합니다:

```tsx
<RootTaleBlogPost
  apiKey={apiKey}
  slugOrId={slug}
  breadcrumb={{ siteUrl: process.env.NEXT_PUBLIC_SITE_URL }}
  // collections 를 함께 주면 "블로그" 세그먼트가 글의 소속 섹션 basePath로
  // 자동 해석됩니다(공지 글 → /notice). showCategory:false 로 카테고리
  // 세그먼트 생략 가능, categoryHref로 링크 override 가능.
/>
```

마지막 항목(카테고리 링크, `showCategory` 기본 `true`)은 `defaultCategoryHref`
(`/blog/categories/{slug}`)를 씁니다 — **이 라우트를 구현해야 브레드크럼·
카테고리 칩 클릭이 404 가 나지 않습니다**(아래 "카테고리 허브 라우트" 참고).

> **마크업 변경 주의** — 헤더 발행일이 `<span data-rt-cms-meta="date">` 에서
> `<time dateTime="…" data-rt-cms-meta="date">` 로 바뀌었습니다. `class`·
> `data-rt-cms-meta` 속성은 그대로라 속성 선택자로 스타일링했다면 영향 없지만,
> 태그명(`span`)을 직접 선택자로 쓴 고객 CSS/스크립트가 있다면 `time` 으로
> 갱신하세요.

### 미리보기 페이지 — 내용 확인과 사이트 화면 확인

관리자(ROOT-ADMIN) 편집기의 **내용 미리보기**는 저장 전 제목·본문·대표 이미지와
커스텀 필드를 확인하는 화면입니다. 커스텀 필드는 필드 이름과 값, 이미지, 반복
항목으로 표시하므로 데이터 전용 콘텐츠도 확인할 수 있습니다. 홈페이지의 실제
배치나 메뉴까지 재현하지는 않습니다.

사이트에 아래 라우트를 배포한 뒤 관리자 **설정 › 외부 연결(Webhook) › 글 미리보기
여는 곳**에서 **사이트 미리보기 연결**을 켜면 **사이트에서 미리보기** 버튼이 추가됩니다.
이 버튼은 `https://{사이트}/preview/post/{글 ID}?token=…`을 열며, 해당 사이트가 구현한
템플릿과 콘텐츠 유형을 지원합니다. 내용 미리보기는 연결 여부와 관계없이 사용할 수 있습니다.

```tsx
// app/preview/post/[id]/page.tsx
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import {
  fetchPostPreview,
  isPreviewExpiredError,
  isPreviewSupersededError,
} from "@roottale/cms-client/server";
import {
  RootTaleBlogPost,
  RootTalePreviewNotice,
} from "@roottale/cms-renderer-next/server";
import { buildPreviewMetadata } from "@roottale/cms-renderer-next/routes";

// 초안이 ISR·CDN 에 남으면 안 된다 — 항상 동적 렌더.
export const dynamic = "force-dynamic";
export const revalidate = 0;

interface Props {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ token?: string }>;
}

export async function generateMetadata({ searchParams }: Props): Promise<Metadata> {
  const { token } = await searchParams;
  const post = token
    ? await fetchPostPreview({
        apiKey: process.env.ROOTTALE_API_KEY!,
        baseUrl: process.env.ROOTTALE_API_BASE,
        token,
      }).catch(() => null)
    : null;
  return buildPreviewMetadata({ title: post?.title }); // 항상 noindex/nofollow
}

export default async function PostPreviewPage({ params, searchParams }: Props) {
  const { id } = await params;
  const { token } = await searchParams;
  if (!token) notFound();

  let expiresAt: string | undefined;
  try {
    const post = await fetchPostPreview({
      apiKey: process.env.ROOTTALE_API_KEY!,
      baseUrl: process.env.ROOTTALE_API_BASE,
      token,
    });
    if (!post || post.id !== id) notFound(); // 토큰은 글 1건 전용
    expiresAt = post.preview.expiresAt;
  } catch (error) {
    if (!isPreviewExpiredError(error) && !isPreviewSupersededError(error)) throw error;
    // 만료·교체된 작업본은 아래 컴포넌트가 안내합니다.
  }

  return (
    <>
      <RootTalePreviewNotice expiresAt={expiresAt} />
      {/* 발행 글 상세와 같은 props 를 쓰되 slugOrId 대신 previewToken 만 넘긴다. */}
      <RootTaleBlogPost
        apiKey={process.env.ROOTTALE_API_KEY!}
        baseUrl={process.env.ROOTTALE_API_BASE}
        previewToken={token}
        relatedPostsCount={3}
      />
    </>
  );
}
```

지켜야 할 것:

- `RootTaleBlogPost`에 `previewToken`을 주면 `slugOrId` 대신 미리보기 조회
  (`fetchPostPreview`)를 쓰고 **같은 템플릿**으로 그립니다. 만료(410)면
  `previewExpiredElement`(기본 안내 문구), 없으면(404) `notFoundElement`.
- 작업본을 새로 저장해 토큰의 버전이 교체되면(409) `previewSupersededElement`를
  표시합니다. 기본 문구는 편집기에서 미리보기를 다시 열도록 안내합니다.
  직접 조회할 때는 `isPreviewSupersededError(error)`로 구분합니다.
- 항상 `dynamic = "force-dynamic"` — 응답이 `no-store` 라도 페이지 자체가 정적
  생성되면 안 됩니다.
- `buildPreviewMetadata`는 항상 `noindex, nofollow` 이며 canonical·og 를 내지
  않습니다. `robots.ts`에도 `disallow: ["/preview/"]`를 더하세요.
- 토큰 없이 접근하면 `notFound()` — 주소만으로는 아무것도 보이지 않습니다.
- 커스텀 템플릿(직접 fetch)이라면 `fetchPostPreview`가 돌려주는 값이
  `fetchPost`와 같은 `CmsPostContent` 형식(+`preview`)이므로 상세 렌더 함수를
  그대로 재사용하면 됩니다.
- 응답에는 저장 전 제목·요약·본문과 함께 커스텀 필드(`fields`)·대표 이미지
  (`featuredImageUrl`)도 편집 중인 값으로 담깁니다. 자기 주소가 없는 정보
  항목(면허·연혁 등)은 그 항목이 들어가는 화면을 그려 보여 주면 됩니다.
- 전체 작업본 토큰은 SEO·분류·관련 콘텐츠·`contentEditor`도 함께 반영합니다.
  `contentEditor.sectionStates`가 `hidden`·`deleted`인 섹션은 출력하지 않습니다.
  `preview.visualTarget`은 이번 응답의 엔티티·작업본 버전·계약·템플릿 표식입니다.
  사이트가 실제로 읽은 공개 의존 버전과 함께 확인하고 다른 작업본 데이터와 섞지 않습니다.

전체 예시는 `examples/nextjs/app/preview/post/[id]/page.tsx` 에 있습니다.

### 다국어 (ADR-0052 A안, W4-6 PR C1/C2)

번역 사이트(어드민에서 "번역 추가"로 언어판을 만든 글)는 `RootTaleBlogList`/
`RootTaleBlogPost`/`RootTalePage` 에 `locale` prop 을 넘기면 그 언어판만
fetch 합니다(`fetchPosts`/`fetchPost` 의 `locale` 쿼리 그대로 전달). 미지정
시 서버가 사이트 기본 locale 만 반환합니다(하위호환).

```tsx
// app/[locale]/blog/[slug]/page.tsx — starter 참조 구현 패턴
const { locale, slug } = await params;
<RootTaleBlogPost
  apiKey={process.env.ROOTTALE_API_KEY!}
  slugOrId={slug}
  locale={locale}
  showTableOfContents
/>;
```

- **URL 전략**(권장, starter 참조 구현) — 기본 locale 은 prefix 없는 기존
  경로(`/blog/{slug}`) 그대로 두고, 나머지 locale 만 `app/[locale]/...` 로
  별도 트리를 둡니다(`app/[locale]/blog/`·`app/[locale]/blog/[slug]/`·
  `app/[locale]/[slug]/`). 사이트 활성 locale 목록은 별도 API 없이
  `fetchBlogSettings().sitemap.locales`(SSoT = `sites.settingsJson.locales`)
  로 얻습니다 — 첫 원소가 기본 locale.
- `<head>` hreflang · 사이트맵 hreflang 은 "SEO 연동" 문서(`seo.md`)의
  "다국어 (hreflang)" 절 참고.
- **UI 문자열**(cms-i18n, ADR-0034 §3) — `RootTaleBlogList.emptyMessage`/
  `allCategoriesLabel`, `RootTaleBlogPost.relatedPostsTitle`/미발견 안내,
  `RootTalePage` 미발견 안내, `RootTaleTableOfContents.title` 은 명시 prop
  을 안 주면 `locale` prop 기준으로 자동 번역됩니다(`@roottale/cms-i18n`
  ko/en 사전, `ja`/`zh-hans` 등 사전 없는 locale 은 ko 로 fallback). 글
  본문·admin UI 는 이 자동 번역 대상이 아닙니다(사람이 직접 작성/ADR-0052
  범위 밖).

### 고정 페이지 (회사소개 등)

어드민의 고정 페이지(`type: "page"`)는 `RootTalePage`로 렌더링합니다 — 블로그
크롬(날짜·작성자·작성자 카드) 없이 제목+본문만 출력합니다 (renderer-next
0.22.0+):

```tsx
// app/about/page.tsx
import { RootTalePage } from "@roottale/cms-renderer-next/server";

export const revalidate = 1800;

export default function AboutPage() {
  return (
    <RootTalePage
      apiKey={process.env.ROOTTALE_API_KEY!}
      baseUrl={process.env.ROOTTALE_API_BASE}
      slugOrId="about"
      // showTitle={false} — 페이지 제목을 직접 마크업할 때
    />
  );
}
```

## 커스텀 경로 — 직접 fetch

```ts
// lib/blog.ts
import { fetchPosts, fetchPost, type CmsPostContent } from "@roottale/cms-client/server";

export async function getAllPosts() {
  const page = await fetchPosts({
    apiKey: process.env.ROOTTALE_API_KEY!,
    baseUrl: process.env.ROOTTALE_API_BASE,
    type: "post",
    limit: 100,
  });
  return page.items; // CmsPostContent[]
  // page.hasMore / page.nextCursor 로 커서 페이지네이션
}

export async function getPost(slug: string) {
  return fetchPost({
    apiKey: process.env.ROOTTALE_API_KEY!,
    baseUrl: process.env.ROOTTALE_API_BASE,
    slugOrId: slug, // slug 또는 UUID — 404면 null 반환
  });
}
```

`CmsPostContent` 주요 필드:

| 필드 | 설명 |
|---|---|
| `id`, `slug`, `title` | 식별자·제목 |
| `excerpt` | 요약 (목록 카드용) |
| `publishedAt` | 발행 시각 (UTC ISO). 화면에는 사이트 운영 시간대로 변환해서 표시 |
| `bodyJson` | 본문 블록 JSON — `RootTaleBlogPost` 또는 `renderBlocks`로 렌더 |
| `terms` | 분류 용어 배열 (`taxonomy: "category" \| "tag"`, `name`, `slug`) |
| `featuredImageUrl` | 대표 이미지 |
| `authorName` | 작성자 표시명 |
| `authorSlug` | 작가 아카이브 slug(`/blog/author/{slug}`) — 미발급 작가는 `null` |
| `metaJson` | 부가 메타 — `metaJson.seo`에 SEO 오버라이드 |
| `patternSlots` | 공통 블록 자리별 블록 key(`{ post_footer: "clinic-guide" }`) — `RootTaleBlogPost`가 자동 렌더, 자체 화면은 `fetchSitePatterns` + `selectSitePatternForSlot`(`theme-and-settings.md` "공통 블록") |

### 발행일 시간대 — 서버 기본값에 맡기지 않기

ROOT-ADMIN은 발행 시점을 UTC ISO 문자열로 저장하고, 관리자 화면에서는 한국 운영
시간대(`Asia/Seoul`)로 표시합니다. `publishedAt`은 날짜 문자열이 아니라 **한 시점**이므로,
커스텀 UI에서 `new Date()` 뒤 서버 기본 시간대로 포맷하거나 `YYYY-MM-DD` 부분만 자르면
UTC 자정 부근의 글이 관리자보다 하루 전 날짜로 보일 수 있습니다. Vercel 같은 서버
런타임은 UTC를 기본값으로 사용할 수 있으므로 실행 환경에 기대지 마세요.

사이트의 운영 시간대를 한 곳에 정하고 `Intl.DateTimeFormat`에 항상 명시합니다. 한국
ROOT-ADMIN 사이트의 기본 구현은 다음과 같습니다.

```tsx
const SITE_TIME_ZONE = "Asia/Seoul";

export function formatPublishedDate(publishedAt: string): string {
  const date = new Date(publishedAt);
  if (Number.isNaN(date.getTime())) return "";

  return new Intl.DateTimeFormat("ko-KR", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: SITE_TIME_ZONE,
  }).format(date);
}

<time dateTime={post.publishedAt}>
  {formatPublishedDate(post.publishedAt)}
</time>;
```

- `dateTime`에는 API 원본 ISO 시각을 그대로 둡니다.
- 보이는 날짜에만 사이트 운영 시간대를 적용합니다.
- 목록 정렬·예약 판정은 보이는 날짜 문자열이 아니라 원본 시각으로 처리합니다.
- 최소 경계 확인값: `2026-08-22T21:40:50.666Z`는 서울에서
  `2026년 8월 23일`이어야 합니다.
- 다른 국가 사이트는 `SITE_TIME_ZONE`만 해당 지역의 IANA 시간대 이름으로 바꾸고,
  목록·상세·OG 이미지 등 모든 날짜 표시가 같은 값을 사용하게 합니다.

### 정적 경로 사전 생성 + 메타데이터

```tsx
// app/blog/[slug]/page.tsx (커스텀 UI 버전)
import type { Metadata } from "next";
import { buildPostMetadata } from "@roottale/cms-renderer-next/routes";
import { getAllPosts, getPost } from "@/lib/blog";

export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map((p) => ({ slug: p.slug }));
}

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) return {};
  // 어드민 글 에디터의 SEO 패널(metaJson.seo) override 적용 + self-canonical.
  // canonical/robots/openGraph 분기를 직접 안 써도 한 곳도 빠뜨리지 않습니다.
  return buildPostMetadata(post, {
    siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
    path: `/blog/${post.slug}`,
  });
}
```

`buildPostMetadata(post, opts)`는 어드민 SEO 패널 값을 Next `Metadata`로
한 줄 변환합니다:

- `seo.title`/`seo.description`/`seo.ogImage` 가 있으면 우선, 없으면 글 값으로 fallback
- `seo.canonical` override → 없으면 `siteUrl`+`path` 로 self-canonical 자동 생성
- `seo.noindex`/`seo.nofollow` 중 하나라도 켜지면 `robots` 출력
- `openGraph`(article·publishedTime·images) 자동 구성

입력은 `{ title, description?, date?, image?, seo? }` 형태면 되고
(`getPost` 의 `BlogPostMeta` 가 그대로 호환), 원본 post 를 쓸 땐
`seo`로 넘길 값은 `(post.metaJson as { seo?: ... }).seo`입니다.

SEO 오버라이드 필드: `title`, `description`, `canonical`, `ogImage`, `ogImageAlt`,
`noindex`, `nofollow`.

`buildPostMetadata`는 글 페이지에 Google 큰 이미지 미리보기
(`max-image-preview:large`)를 기본으로 허용합니다. `ogImageAlt`가 있으면 OG 이미지의
대체 텍스트로 사용하고, 없으면 검색 제목을 사용합니다.

### slug 변경 시 301 리다이렉트 (필수 권장)

어드민에서 글 slug를 바꿔도 API는 **옛 slug로 글을 찾아 현재 slug로
응답**합니다(slug history fallback). 페이지에서 요청 slug와 응답 slug가
다르면 301로 보내야 검색엔진 순위가 새 URL로 승계됩니다:

```tsx
// app/blog/[slug]/page.tsx
import { notFound, permanentRedirect } from "next/navigation";
import { postRedirectPath } from "@roottale/cms-renderer-next/routes";

export default async function PostPage({ params }: Props) {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) notFound();
  const redirect = postRedirectPath(post, slug); // 기본 basePath "/blog"
  if (redirect) permanentRedirect(redirect);
  // ... 렌더
}
```

`generateMetadata`는 redirect 페이지에서 실행돼도 무방하지만, canonical을
직접 계산한다면 `post.slug`(현재 slug) 기준으로 계산하세요.

## 캐싱 전략

- 페이지에 `export const revalidate = 1800` (30분) — **fallback일 뿐**입니다.
- 정상 동작은 발행 웹훅이 즉시 revalidate 하는 것 → `revalidation-webhooks.md`
  를 반드시 함께 설정하세요.
- 홈 화면에 최신 글 섹션을 둔다면 홈도 웹훅의 `alsoRevalidate`에 포함하세요.

완전한 동작 예시는 MCP tool `readRootTaleNextjsExampleCode`로 확인할 수 있습니다.
