UNPKG

@roottale/cms-mcp

Version:

RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.

486 lines (389 loc) • 24.6 kB
--- title: 콘텐츠 유형 (Collections) description: 같은 글 풀을 공지 게시판(/notice)·블로그(/blog) 등 여러 섹션으로 나누는 법. 섹션=글의 collection_key, 카테고리=섹션 안의 주제. URL 구조, 어드민 설정, 연동 코드, slug·301·OG. --- # 콘텐츠 유형 (Collections) 하나의 글 목록을 **여러 섹션(stream)**으로 나눠 서로 다른 URL·레이아웃으로 보여주는 기능입니다. 가장 흔한 형태는 **공지 게시판(`/notice`) + 블로그(`/blog`)** 분리입니다. > **핵심 모델 (2024 ADR-0060 Amendment 1):** > 글은 **하나의 섹션**에 속하고(`collection_key`), 그 안에서 여러 **주제**(category)를 > 가질 수 있습니다. 섹션은 글쓰기 화면의 **"어디에 올릴까요?"**에서 고르고, 주제는 > 섹션 안의 세부 분류(예: 블로그의 *칼럼*·*소식*)입니다. ## URL이 어떻게 정해지나 > **글의 URL = 그 글이 속한 섹션의 `basePath` + `/{slug}`** — 섹션은 글의 `collection_key`로 정해집니다. | 글의 섹션 (`collection_key`) | basePath | URL | |---|---|---| | `notice` (공지) | `/notice` | `/notice/{slug}` | | `blog` (블로그) | `/blog` | `/blog/{slug}` | 예: 섹션이 `notice`인 글 "개강안내" → `https://내사이트/notice/개강안내` 섹션이 `blog`인 글 "비문학공부법" → `https://내사이트/blog/비문학공부법` 섹션별로 함께 만들어지는 경로: | 경로 | 설명 | |---|---| | `{basePath}` | 섹션 목록 (예: `/notice`, `/blog`) | | `{basePath}/{slug}` | 글 상세 (**`detail` 켠 섹션만** — 아래 "목록 전용 유형" 참고) | | `{basePath}/categories/{slug}` | **주제** 아카이브 (`archives` 켠 섹션만) | | `/feed.xml` | RSS — `feed` 켠 섹션들의 통합 피드 (단 `detail:false` 섹션 글은 제외) | | `/sitemap.xml` | 글마다 **소속 섹션 basePath로** 정확히 매핑 (`detail:false` 섹션 글은 미포함) | | `{basePath}/{slug}/opengraph-image` | 글별 동적 OG 카드 (배선 시) | 규칙: - **slug은 한글 그대로** 됩니다(예: `/blog/비문학독해`). 내부적으로 percent-encoding. - **같은 글이 두 섹션에 안 뜸**: 공지 글을 `/blog/개강안내`로 열면 404, 반대도 404(가드). - **섹션(`collection_key`)이 없는 글**은 sitemap·상세 라우트에서 제외됩니다. ### 카테고리를 주소에 넣는 유형 칼럼처럼 카테고리가 정보 구조의 일부라면 유형별로 아래 정책을 켤 수 있습니다. ```ts const COLUMN: RouteCollection = { key: "column", basePath: "/column", categories: ["headache", "dizziness"], archives: true, detailPath: "category", categoryPath: "direct", categoryCardinality: "exactly-one", }; ``` 이 설정은 카테고리 허브를 `/column/{categorySlug}`, 글 상세를 `/column/{categorySlug}/{postSlug}`로 만듭니다. `categoryPath`를 생략하면 기존 형식인 `/column/categories/{categorySlug}`를 유지합니다. `detailPath`를 생략하면 글 상세도 기존의 `/column/{postSlug}`를 유지합니다. `detailPath: "category"`는 `archives: true`와 `categoryCardinality: "exactly-one"`이 반드시 필요합니다. ROOT-ADMIN은 공개·예약 글의 카테고리가 정확히 하나인지 서버에서 검증하며, 기존 공개·예약 글에 누락이 있으면 이 정책 자체를 저장하지 않습니다. 이미 주소에 쓰이는 카테고리의 slug·소속·삭제도 URL 이전 계획 없이 바로 바꿀 수 없습니다. ## 주소 없는 유형 (`base_path: ""`) — 페이지 안에서만 쓰는 콘텐츠 강사·리뷰처럼 **독립된 URL이 없고 홈페이지의 다른 페이지 안에서 불러와 쓰는** 콘텐츠는 섹션의 **주소 경로를 비워두면** 됩니다. `base_path`가 빈 문자열이면: - `resolvePostUrl`/`resolvePostPath` (cms-core) 가 이 섹션 글에 대해 항상 **`null`** 을 반환 — `detail: false`(목록 전용) 여부와 무관합니다. - 라우트·sitemap·feed·`/{basePath}/categories/{slug}` 아카이브를 **일절 파생하지 않습니다**. `createSitemapIndex`/`createFeedRoute` 등 route 팩토리에 넘겨도 이 섹션의 글은 조용히 빠집니다(에러 아님). - 소속 판정(`resolvePostCollection`)은 영향 없습니다 — 글은 여전히 이 섹션에 속하고, 글쓰기 화면의 "어디에 올릴까요?" 에도 그대로 나타납니다. **주소와 소속은 별개**입니다. - 외부 사이트는 이 유형의 내용을 **posts API의 `collectionKey` 필터** (`fetchPosts({ collectionKey: "instructors" })`)로 가져와 원하는 페이지 안에서 직접 렌더합니다. `RootTaleBlogList` 를 이 유형에 임베디드로 쓸 때는 자체 `postHref` 를 제공하세요 — 컴포넌트의 기본 링크 로직은 이 유형의 글에 목록 페이지 폴백조차 만들지 않습니다(목록 페이지 자체가 없으므로). ```ts export const COLLECTIONS: RouteCollection[] = [ { key: "blog", basePath: "/blog", categories: ["column", "news"], feed: true, archives: true }, // 주소 없음 — 강사 소개는 /about 페이지 안에서 fetchPosts 로 불러와 렌더. { key: "instructors", basePath: "", categories: [] }, ]; ``` 어드민 "콘텐츠 유형" 편집기에서는 **주소 경로 칸을 비워두면** 됩니다 — 비우면 자동으로 RSS 피드·카테고리 모음·공유 미리보기 이미지·글별 상세 페이지 토글이 꺼지고 비활성화됩니다(주소가 없으니 의미가 없는 기능들). 카드에는 "주소 없음" 표시가 붙습니다. ## 목록 전용 유형 (`detail: false`) — 상세 페이지 없음 글별 상세 라우트를 만들지 않고 **목록 화면에서만 보여주는** 섹션을 만들 수 있습니다. 가장 흔한 예는 **후기**(`/reviews`) — 목록에 전문을 그대로 노출하고, 글마다 별도 URL로 들어가는 상세 페이지는 없는 경우입니다. 어드민 "콘텐츠 유형" 편집기에서 각 유형의 **"글별 상세 페이지"** 토글을 끄면 됩니다 (기본은 켜짐 — 기존 유형은 그대로 상세 페이지를 가집니다). 끄면: - `resolvePostUrl`/`resolvePostPath` (cms-core) 가 이 섹션 글에 대해 **`null`** 을 반환 — 글쓰기 화면의 "어디에 올릴까요?" 는 그대로 노출되지만(소속 판정과 상세 URL 존재 여부는 별개), sitemap·feed·llms.txt 는 이 글의 **상세 URL 을 발행하지 않습니다**(존재하지 않는 페이지로 404 유발 방지). - `RootTaleBlogList`/관련 글 카드의 링크는 상세 URL 대신 **그 섹션의 목록 페이지 (`basePath`)** 로 향합니다 — 카드가 이미 목록에서 전문을 보여주므로 상세 이동 없이도 의미가 있습니다. - 사이트 코드 변경은 필요 없습니다 — 이 값은 route 팩토리(`createSitemapIndex`/ `createFeedRoute`/`createLlmsTxtRoute`)가 넘겨받는 `collections` 배열의 값일 뿐입니다. ```ts export const COLLECTIONS: RouteCollection[] = [ { key: "notice", basePath: "/notice", categories: [] }, { key: "blog", basePath: "/blog", categories: ["column", "news"], feed: true, archives: true }, // 목록 전용 — 후기는 /reviews 목록에서 전문 노출, 글별 상세 URL 없음. { key: "reviews", basePath: "/reviews", categories: [], detail: false }, ]; ``` > 필드명은 `detail` (camelCase, cms-core `RouteCollection`), 공개 API 응답은 > `detail`(snake_case 와 동일 철자). 미설정 시 기본값은 `true`(하위 호환 — 기존 사이트는 > 아무 것도 안 바꿔도 그대로 상세 페이지를 가집니다). ## 섹션 vs 주제 (자주 헷갈리는 부분) | | 섹션 (collection) | 주제 (category) | |---|---|---| | 무엇 | 글이 사는 곳 (공지 / 블로그) | 섹션 안의 세부 분류 (칼럼 / 소식) | | 글당 | **딱 하나** (배타적) | 기본 0개 이상, 유형 정책으로 정확히 1개 가능 | | 정하는 곳 | 글쓰기 "어디에 올릴까요?" | 글 > 분류 > 카테고리 / 글쓰기 주제 칩 | | 저장 | `post.collection_key` | 글의 category terms | | 라우팅 | basePath 결정 (`/notice`) | 아카이브만 (`/blog/categories/칼럼`) | > 이전 버전은 *카테고리로 섹션을 추론*했지만, 지금은 섹션이 글에 **명시**됩니다. > 카테고리는 글의 섹션을 결정하지 않습니다. 카테고리 자체에는 사용할 섹션을 > 연결할 수 있고, 글에서는 그 섹션에 연결된 카테고리만 주제로 고릅니다. ## 어드민에서 설정 (`admin.roottale.com`) **설정 > 콘텐츠 유형** 에서 섹션을 정의합니다. 빈 상태의 "공지 + 블로그 한 번에 만들기" 버튼으로 표준 두 섹션을 한 번에 만들 수 있습니다. 각 섹션은: | 항목 | 의미 | |---|---| | key | 안정 식별자 (`notice`, `blog`) — 사이트 코드와 맞물리므로 보통 고정 | | 라벨 | 메뉴·작성 화면 표시 이름 (공지/블로그) | | basePath | URL 앞부분 (`/notice`, `/blog`). **비워두면 주소 없는 유형** — 아래 "주소 없는 유형" 참고 | | feed / archives / og | RSS 포함 / 주제 아카이브 / 동적 OG | | 글별 상세 페이지 (`detail`) | 기본 켜짐. 끄면 목록 전용(상세 URL 없음) — 아래 "목록 전용 유형" 참고 | | 상세 주소 (`detail_path`) | `flat`(기본) 또는 `category` — 카테고리를 상세 주소에 포함 | | 카테고리 주소 (`category_path`) | `namespaced`(기본 `/categories/{slug}`) 또는 `direct`(`/{slug}`) | | 카테고리 개수 (`category_cardinality`) | `multiple`(기본) 또는 `exactly-one` | | 순서 | 메뉴·표시 순서 | **섹션을 하나도 안 만들면 단일 블로그(`/blog`)** 로 동작합니다(설정 전 기본값). 카테고리 소속은 **글 > 분류 > 카테고리**에서 정합니다. 카테고리를 만들거나 편집할 때 콘텐츠 유형을 하나 고르면, 공개 `collections[].categories`에도 그 유형의 주제로 나타납니다. 콘텐츠 유형 설정과 카테고리 소속을 서로 다른 화면에서 동시에 바꿔도 JSON 배열을 덮어쓰지 않도록 별도 데이터로 저장됩니다. ### ⚠️ basePath는 "라우트가 있어야" 동작합니다 (데이터=DB, 라우트=코드) basePath·라벨·플래그는 어드민에서 바꾸면 sitemap·feed·라우팅이 즉시 따라갑니다. **단 basePath에 해당하는 페이지 파일이 사이트에 있어야** 실제로 열립니다: - `/notice`·`/blog`처럼 **이미 라우트가 있는 경로**는 어드민만으로 자유롭게 편집 → 동작. - basePath를 **완전히 새 경로**(예: `/news`)로 바꾸면 sitemap엔 `/news/{slug}`가 나가지만 사이트에 `app/news/[slug]` 라우트가 없으면 **404**. 개발자가 라우트를 먼저 추가해야 합니다. (새 basePath도 코드 수정 없이 동작시키려면 catch-all 동적 라우트 — 아래.) ### 글을 섹션에 올리기 글쓰기 화면 맨 위 **"어디에 올릴까요?"**에서 공지/블로그 카드를 고릅니다 — 이게 글의 섹션(`collection_key`)이 됩니다. 그 아래 **주제**는 고른 섹션의 카테고리만 보입니다 (블로그면 칼럼·소식 등). 주제는 선택이며, **글 > 분류 > 카테고리**에서 미리 만들어 콘텐츠 유형에 연결합니다. ### 콘텐츠 유형별 커스텀 필드 (ACF 방식) **글 > 필드 그룹**에서 콘텐츠 유형마다 별도 입력칸을 만들 수 있습니다. 새 필드 그룹의 적용 기준을 **콘텐츠 유형**으로 고른 뒤 `doctors`, `reviews` 같은 유형을 선택하면, 그 유형의 글 편집 화면에만 해당 입력칸이 나타납니다. 카테고리를 임시로 붙일 필요가 없습니다. 필드 값은 글의 `meta_json.acf`에 저장되며 공개 글 API에서는 정의에 맞게 변환된 `fields`와 표시용 `fields_meta`로 제공됩니다. 이미지·관계 필드는 raw ID가 아니라 공개 URL과 안전한 참조 객체로 해석됩니다. ```ts const doctors = await fetchPosts({ apiKey: process.env.ROOTTALE_API_KEY!, collectionKey: "doctors", }); for (const doctor of doctors.items) { // 예: { name, specialty, photo, education, schedule, ... } console.log(doctor.fields); } ``` ROOT-ADMIN의 코드 정의 필드 그룹도 같은 규칙을 씁니다. 의료 vertical의 기본 `의료진 정보` 그룹은 `doctors` 콘텐츠 유형에 연결되며 이름·전문분야·사진·대체 텍스트·학력/경력 반복 목록·진료 시간표·담당 치료·검수 책임자를 제공합니다. ## 사이트 연동 코드 섹션 선언을 route 팩토리에 넘기면 sitemap·feed·revalidate가 거기서 파생됩니다. 두 가지 방식이 있습니다. ### 방식 A — 코드 상수 (간단, 고정) ```ts import type { RouteCollection } from "@roottale/cms-renderer-next/routes"; export const COLLECTIONS: RouteCollection[] = [ { key: "notice", basePath: "/notice", categories: [] }, // 주제 없는 게시판 { key: "blog", basePath: "/blog", categories: ["column", "news"], // 이 섹션의 주제(아카이브 범위) feed: true, archives: true, }, ]; ``` > `categories`는 이제 **그 섹션이 제공하는 주제 목록**(아카이브 `/blog/categories/{slug}` > 생성 범위)입니다. 섹션 소속은 글의 `collection_key`로 정해지므로, 이 배열은 라우팅 > 소유권이 아닙니다. ```ts // app/sitemap.ts import { createSitemapIndex } from "@roottale/cms-renderer-next/routes"; const { generateSitemaps, sitemap } = createSitemapIndex( { apiKey, siteUrl, title, collections: COLLECTIONS }, [ /* 정적 경로 */ ], ); export { generateSitemaps }; export default sitemap; // app/feed.xml/route.ts export const dynamic = "force-dynamic"; export const GET = createFeedRoute({ apiKey, siteUrl, title, collections: COLLECTIONS }); ``` ### 방식 B — 어드민에서 동적 로드 (운영자가 직접 편집) 상수 대신 **어드민 "콘텐츠 유형"** 값을 `fetchCollections()`로 가져와 팩토리에 **resolver 함수**로 넘깁니다. 운영자가 어드민에서 섹션을 바꾸면 사이트가 따라갑니다. ```ts import { COLLECTIONS_CACHE_TAG, fetchCollections, } from "@roottale/cms-client/server"; const DEFAULT: RouteCollection[] = [ /* 위와 동일 — fail-soft 기본값 */ ]; async function getCollections(): Promise<RouteCollection[]> { try { const c = await fetchCollections({ apiKey: process.env.ROOTTALE_API_KEY!, tags: [COLLECTIONS_CACHE_TAG], // 어드민 저장 시 즉시 반영 (아래 revalidate 절) }); return c.length ? c : DEFAULT; } catch { return DEFAULT; // API 미설정/실패 시 기본값 } } const { generateSitemaps, sitemap } = createSitemapIndex( { apiKey, siteUrl, title, collections: getCollections }, [ ], ); export { generateSitemaps }; export default sitemap; export const GET = createFeedRoute({ apiKey, siteUrl, title, collections: getCollections }); ``` 공개 엔드포인트: `GET /v1/cms/public/collections` (블로그 조회와 같은 API 키). 응답은 `RouteCollection`과 구조 호환이라 그대로 넘길 수 있습니다. 매 요청 fetch를 피하려면 사이트 경계에서 캐시하세요(예: Next `fetch(url, { next: { revalidate: 300 } })`). `categories`는 콘텐츠 유형 설정 JSON이 아니라 카테고리의 현재 소속을 기준으로 서버가 조립하므로, 카테고리 이름 변경·삭제·이동이 즉시 반영됩니다. 빈 배열은 catch-all이 아니라 **그 유형에 연결된 카테고리가 없음**을 뜻합니다. ### 섹션 목록 페이지 (공지/블로그 분리 렌더) 각 섹션 목록은 `RootTaleBlogList` 에 **`collection`+`collections`** 를 넘겨 그 섹션 글만 보이게 합니다. **이걸 안 주면 컴포넌트가 전체 글을 렌더**하므로 공지 글이 `/blog` 목록에 섞여 들어옵니다(섹션을 나눈 사이트의 가장 흔한 버그). `collections` 를 주면 글 링크도 소속 섹션 basePath 로 자동 라우팅됩니다(공지→`/notice/{slug}`). 서버(api-core `collection_key=`)가 fetch 단계에서부터 그 섹션 글만 가져오므로 `limit`(예: `limit=10`)이 다른 섹션 글에 낭비되지 않습니다. ```tsx import { RootTaleBlogList } from "@roottale/cms-renderer-next/server"; import { COLLECTIONS } from "@/lib/collections"; // 위 "방식 A" 의 상수 // app/notice/page.tsx — 공지 게시판 export default function NoticePage() { return ( <RootTaleBlogList apiKey={process.env.ROOTTALE_API_KEY!} collection="notice" collections={COLLECTIONS} /> ); } // app/blog/page.tsx — 블로그 export default function BlogPage() { return ( <RootTaleBlogList apiKey={process.env.ROOTTALE_API_KEY!} collection="blog" collections={COLLECTIONS} showCategoryFilter /> ); } ``` `RootTaleBlogCategories` 도 같은 `collection`+`collections` 를 받아 그 섹션의 주제만 집계합니다. 카테고리 칩/사이드바를 섹션별로 나눌 때 쓰세요. #### `/blog` 가 선언 섹션이 *아닌* 사이트 — `excludeCollections` (네거티브 스코프) 증상/질환/치료처럼 **아카이브 전용 스트림만 선언하고, 나머지("미소속") 글을 `/blog` 로 보여주는** 사이트도 있습니다. 이런 사이트는 `blog` 라는 섹션 자체가 없으므로 `collection="blog"` 로 스코프할 수 없습니다 — 대신 `collections`+ **`excludeCollections`** 로 "어느 스트림에도 안 속한 글만" 골라냅니다. ```tsx // app/blog/page.tsx — 증상/질환/치료 스트림은 따로, 나머지는 블로그 import { RootTaleBlogList } from "@roottale/cms-renderer-next/server"; import { ARCHIVE_COLLECTIONS } from "@/lib/collections"; // symptoms/conditions/treatments export default function BlogPage() { return ( <RootTaleBlogList apiKey={process.env.ROOTTALE_API_KEY!} collections={ARCHIVE_COLLECTIONS} excludeCollections showCategoryFilter /> ); } ``` ⚠️ **`blog` 자체가 선언 섹션인 사이트에는 쓰지 마세요.** `collections` 목록에 `{ key: "blog", ... }` 가 있고 글의 `collectionKey === "blog"` 라면, 그 글은 "소속 글"로 판정되어 `excludeCollections` 가 오히려 **전부 제외**해 버립니다(빈 목록). 그런 사이트는 위 "섹션 목록 페이지" 예시처럼 포지티브 `collection="blog"` 가 정경로입니다. 규칙: - `collection` 과 `excludeCollections` 동시 지정 = **throw**(포지티브/네거티브 배타). - `collections` 없이 `excludeCollections` 만 지정 = **throw**(조용한 no-op 금지). > 동적 basePath(어드민에서 자유 편집)나 catch-all 라우트를 쓰면 `collection` 값을 > 요청 경로에서 판정해 넘기세요(아래 "동적 basePath" 참고). ### 상세 페이지 가드 (섹션 누출 차단) 상세 라우트는 글이 그 섹션 소속인지 확인해 다른 섹션 글이 새는 것을 막습니다. `resolvePostCollection`은 글의 `collectionKey`로 섹션을 해석합니다(공개 API가 글마다 `collection_key`를 내려줍니다 → `cms-client`의 `CmsPostContent.collectionKey`). ```ts import { resolvePostCollection } from "@roottale/cms-renderer-next/routes"; // app/blog/[slug]/page.tsx const post = await getPost(slug); if (!post || resolvePostCollection(post, COLLECTIONS)?.key !== "blog") notFound(); ``` ### 상세 페이지 메타데이터 (canonical 공지/블로그 구분) 상세 라우트의 `generateMetadata` 도 `collections` 를 넘겨야 canonical 이 글의 섹션에 맞게 나옵니다. `path` 를 `/blog/...` 로 하드코딩하면 공지 글이 잘못된 블로그 canonical 을 갖게 됩니다. ```ts import { buildPostMetadata } from "@roottale/cms-renderer-next/routes"; // app/blog/[slug]/page.tsx (공지면 app/notice/[slug]) return buildPostMetadata(post, { siteUrl: process.env.NEXT_PUBLIC_SITE_URL, collections: COLLECTIONS, // 글의 collectionKey 로 /notice·/blog canonical 자동 해석 }); ``` 원본 post 를 넘기면 `post.path`(플랫폼이 저장한 정규 공개 경로, ADR-0105)가 먼저 canonical 이 되고 `collections` 는 저장 경로가 없는 글의 폴백입니다. `RootTaleBlogList`·`RootTaleBlogPost`(연관 글·빵부스러기)의 글 링크도 같은 순서 — `post.path` → `collections` 규칙 → `/blog/{slug}` — 로 정해집니다. 자세한 동작은 `seo.md` 의 "글 메타데이터 → 공지·블로그 다중 스트림" 참고. ### revalidate ```ts import { revalidatePath, revalidateTag } from "next/cache"; import { THEME_CACHE_TAG } from "@roottale/cms-client/server"; import { createRevalidateRoute } from "@roottale/cms-renderer-next/routes"; export const POST = createRevalidateRoute({ apiKey, // 2번째 인자(type)를 반드시 그대로 넘긴다 — 안 넘기면 레이아웃 전역 무효화가 // 페이지 1개 무효화로 줄어든다. revalidate: (path, type) => revalidatePath(path, type), collections: COLLECTIONS, // 어드민에서 콘텐츠 유형·메뉴·사업장 정보 등 **설정**을 저장했을 때 그 값을 // 담은 fetch 캐시를 지운다. `{ expire: 0 }` 이어야 즉시 만료다 // (revalidation-webhooks.md §1 "설정 저장"). revalidateTag: (tag: string) => revalidateTag(tag, { expire: 0 }), themeTag: THEME_CACHE_TAG, }); ``` 각 섹션 basePath(+ `archives`면 `/categories`)와 `/feed.xml`·`/sitemap.xml`·`/llms.txt`를 자동 무효화합니다. resolver가 실패하면 잘못된 경로를 추측하지 않고 불변 경로만 갱신하며 응답에 `warning`을 노출합니다. `fetchCollections`로 유형을 동적 로드한다면 그 조회에도 `tags: [COLLECTIONS_CACHE_TAG]`를 붙이세요 — 어드민에서 유형을 추가·수정했을 때 사이트가 옛 목록을 붙들고 있지 않게 됩니다. ### 동적 OG 이미지 ```tsx // app/blog/[slug]/opengraph-image.tsx import { ImageResponse } from "next/og"; import { createPostOgImage, OG_IMAGE_SIZE, OG_IMAGE_CONTENT_TYPE, type ImageResponseLike, } from "@roottale/cms-renderer-next/routes"; export const size = OG_IMAGE_SIZE; export const contentType = OG_IMAGE_CONTENT_TYPE; export default createPostOgImage( { apiKey, siteUrl, title, brandLabel: "내 사이트" }, { ImageResponse: ImageResponse as unknown as ImageResponseLike }, // Next 16 타입 cast ); ``` ## slug 변경과 301 글의 slug(`/{slug}` 부분)는 글 편집 화면에서 바꿉니다. 바꾼 뒤 옛 slug로 들어오면 `postRedirectPath`로 **301 리다이렉트**되어 새 slug로 넘어갑니다(검색 순위 보존). ## 동적 basePath (advanced) basePath를 **코드 수정 없이 어드민에서 자유롭게** 바꾸고 싶으면, 정적 `app/notice/[slug]` 대신 **catch-all 동적 라우트** `app/[stream]/[slug]/page.tsx`(또는 `app/[...path]`)를 두고, 그 안에서 collections를 읽어 요청 경로가 어떤 섹션 basePath인지 판정해 렌더합니다. 그러면 어드민에서 basePath를 `/news`로 바꿔도 동작합니다. 트레이드오프: 정적 라우트보다 캐시·타입 안전성이 떨어지므로, 섹션 구조가 자주 바뀌는 사이트에만 권장합니다. ## 자주 막히는 곳 - **글이 안 보여요** → 글에 **섹션(`collection_key`)**이 지정됐는지 확인. 글쓰기 "어디에 올릴까요?"에서 섹션을 골라야 합니다. (섹션 없는 글은 sitemap·상세에서 제외.) - **404가 떠요** → 공지 글을 `/blog/...`로(또는 그 반대로) 열면 가드가 막습니다. 올바른 섹션 basePath로 접근하세요. basePath를 바꿨다면 사이트에 그 라우트 파일이 있는지 확인. - **주제 아카이브가 비어요** → 그 주제(카테고리)가 섹션의 `categories`(주제 목록)에 있고 `archives`가 켜져 있는지 확인. - **sitemap에 글이 빠졌어요** → 그 글에 섹션이 없거나, 소속 섹션의 `base_path`가 빈 값(주소 없는 유형)이면 의도적으로 제외됩니다. - **`RootTaleBlogList` 카드를 눌렀는데 이상한 곳으로 가요** → 그 글의 섹션이 주소 없는 유형이면 목록 페이지가 없어 기본 링크 로직이 레거시 `/blog/{slug}` 로 폴백합니다. 이 유형은 `RootTaleBlogList` 로 임베디드 렌더하지 말고 `fetchPosts({ collectionKey })` 로 직접 페이지에 꽂아 쓰세요.