SEO — RSS·사이트맵·JSON-LD
@roottale/cms-renderer-next/routes의 팩토리로 RSS·사이트맵을 한 줄에
구성하고, @roottale/cms-client/server의 헬퍼로 JSON-LD를 생성합니다.
고정 페이지의 검색·공유 메타데이터는 아래 공통 메타데이터를 참고하세요.
RSS 피드
// app/feed.xml/route.ts
import { createFeedRoute } from "@roottale/cms-renderer-next/routes";
export const dynamic = "force-dynamic";
export const GET = createFeedRoute({
apiKey: process.env.ROOTTALE_API_KEY!,
apiBase: process.env.ROOTTALE_API_BASE,
siteUrl: process.env.NEXT_PUBLIC_SITE_URL!,
title: "예시 블로그",
description: "예시 블로그 설명",
});
발행된 글이 자동 포함된 RSS 2.0 XML을 반환합니다.
공통 메타데이터
ROOT-ADMIN 설정 → 검색·공유 표시에서 홈·코드 페이지·목록 첫 화면·글·분류를 관리합니다. 제목·설명·공유 이미지·이미지 대체 텍스트·noindex·nofollow를 사이트가 지원하는 범위에서 편집합니다. 등록·수정·초기화는 Pro/Premium 또는 루트테일이 해당 사이트에 이 기능을 허용한 경우에 가능합니다. 루트테일이 사이트별로 제한하면 요금제와 관계없이 편집이 닫힙니다. 기본 요금제로 내려가거나 허용이 풀려도 기존 설정의 공개 적용과 읽기·내보내기는 유지됩니다. 일반 본문 편집과 대표 이미지 변경은 이 제한과 별개입니다.
본문이 없는 페이지는 콘텐츠 계약 metadata.routes에 안정적인 routeKey를 등록합니다. 코드 화면은 source: { kind: "code", path: "/about" }, 기존 본문 페이지는 { kind: "page", pageKey: "about" }, 모델 목록은 { kind: "model-list", modelKey: "column" }으로 선언합니다. CMS 페이지를 메타데이터 저장 용도로 새로 만들 필요가 없습니다. 주소를 바꿔도 같은 페이지의 routeKey는 유지합니다. SDK 설치만으로 편집을 열지는 않으며 실제 배포 계약·연동 증거가 필요합니다.
import { fetchRouteMetadata } from "@roottale/cms-client/server";
import { buildPageMetadata } from "@roottale/cms-renderer-next/routes";
export async function generateMetadata() {
const route = await fetchRouteMetadata({
apiKey: process.env.ROOTTALE_API_KEY!, routeKey: "about", locale: "ko",
});
return buildPageMetadata({
...route,
fallback: { title: "소개 | 예시 사이트", description: "사이트 소개" },
}, {
canonical: "https://example.com/about",
verification: route ? {
routeKey: route.routeKey, locale: route.locale, version: route.version,
// 사이트가 배포한 콘텐츠 계약 체크섬도 함께 전달합니다.
contractChecksum: process.env.ROOTTALE_CONTENT_CONTRACT_CHECKSUM,
} : undefined,
});
}
fetchRouteMetadata는 공개 API를 고유 키로 한 번 조회합니다. null은 등록·연결된 경로가 없다는 정상 응답이고, 연결됐지만 직접 설정이 없으면 overrides: {}인 객체입니다. HTTP·네트워크·잘못된 응답은 예외입니다. 예외를 null로 바꿔 장기 캐시하지 마세요. 오류를 기록하고 코드 기본값으로 화면을 유지하는 예시는 lib/route-metadata.ts에 있습니다.
여러 페이지와 사이트맵에서 공유하는 조회
등록된 고정 경로를 여러 페이지나 사이트맵에서 읽을 때는 fetchSiteRouteMetadata를
사용합니다. 한 경로만 필요한 연동은 기존 fetchRouteMetadata를 계속 사용할 수 있습니다.
새 함수는 { site_id, routes }를 반환하며, 각 항목은 단건 함수의 반환 객체와 같습니다.
계약 순서로 반환하고 단건이 null인 미발행·비공개·누락 경로는 제외합니다.
등록 경로는 계약당 최대 2,000개입니다. 일반 글·분류 전체를 조회하는 API는 아닙니다.
import { cache } from "react";
import { fetchSiteRouteMetadata } from "@roottale/cms-client/server";
export const loadSiteRouteMetadata = cache((locale = "ko") => fetchSiteRouteMetadata({
apiKey: process.env.ROOTTALE_API_KEY!,
baseUrl: process.env.ROOTTALE_API_BASE,
locale,
revalidate: 300,
}));
// generateMetadata와 sitemap이 같은 로더를 사용합니다.
const { routes } = await loadSiteRouteMetadata();
const about = routes.find((route) => route.routeKey === "about");
React cache는 렌더 안에서 조회를 공유하고, SDK의 Next fetch cache는 렌더 사이에서
공유합니다. locale과 siteId가 다른 요청은 분리됩니다. signal을 전달할 수 있고
revalidate: 0이면 재검증 주기를 0으로 지정합니다. 기본 주기는 300초이며
METADATA_CACHE_TAG·SITE_METADATA_DEFAULTS_CACHE_TAG가 자동 부착됩니다.
기존 웹훅의 메타데이터 태그 무효화가 이 조회에도 적용됩니다.
createRevalidateRoute에 contentPolicies: 등록된정책 ?? {}와 즉시 만료하는
revalidateTag 콜백을 전달해야 글·미디어·metadata.updated가 이 태그를 지웁니다.
정책이 없는 사이트도 빈 객체를 전달합니다(starter와 Next.js 예제 참고).
배포 순서는 API → SDK 발행 → 사이트 SDK 업그레이드·배포입니다.
새 API보다 SDK 호출이 먼저 적용되면 404 예외가 발생합니다. HTTP·네트워크·응답 형식
오류를 빈 목록으로 저장하지 마세요. 호출한 화면에서 오류를 기록하고 코드 기본값을
사용합니다. starter도 이 경로로 처리하며, 성공 응답이어도 공개 경로가 사이트 코드와
다르면 원격 값을 적용하지 않습니다. 실행 예시는 examples/nextjs/lib/route-metadata.ts의
공유 로더와 경로별 선택을 참고하세요.
해석 순서는 필드별 직접 설정 → 콘텐츠/코드 기본값 → 사이트 기본값 → 코드 fallback입니다. false는 명시값이며 강제 미리보기·비공개 제한이 우선합니다. buildPageMetadata는 최종 제목을 title.absolute로 내보내고 OG·X에 같은 문구와 이미지 대체 텍스트를 적용합니다. 기존 Googlebot 제한은 googleBot 옵션으로 전달합니다. canonical은 사이트 코드가 canonical 또는 siteUrl+path로 정하며 canonical: null이면 생략합니다. 기존 buildPostMetadata의 seo.canonical은 기본 유지하고, 코드 소유 사이트는 allowCanonicalOverride: false로 고정합니다.
글은 공개 응답의 metaJson.seo, 분류는 seoTitle/seoDescription/seoOgImage/seoOgImageAlt/seoNofollow를 같은 빌더의 overrides에 연결합니다. 분류 색인 여부는 기존 hubPromoted 정책을 유지합니다. 글마다 경로 메타데이터 API를 추가 호출하지 않습니다. 본문이 있는 CMS 페이지는 lib/page-metadata.ts 예시처럼 기존 글 원본을 사용합니다.
동적 기본값은 등록 계약의 metadata.posts/terms.defaultRules[modelKey]와 FRONT의 formatMetadataDefaults(input, metadata)에 같은 선언을 사용합니다. title/description.source: "template"은 {{title}}과 {{field:필드이름}}만 치환합니다. fields에는 공개 글의 post.fields를 전달하며 문자열 필드만 사용합니다. 객체·배열·누락 필드는 빈 문자열로 처리하고, 필드 안의 토큰을 다시 해석하지 않습니다. normalizeWhitespace: true로 비어 있는 선택 필드 사이의 공백을 정리합니다. 실행식·정규식은 받지 않습니다. 실행 가능한 연동 예시는 examples/nextjs/lib/content-metadata.ts입니다.
요약이 없을 때 본문 문단을 사용하는 사이트는 description.bodyFallback: {}와 bodyParagraphs: metadataBodyParagraphs(post.bodyJson)를 연결합니다. preferContaining은 포함 문구가 있는 첫 문단을 우선하고, 없으면 첫 문단을 사용합니다. stripLeadingLabel: "conclusion"은 이 본문 대체값에서 기존 한국어 “결론부터 말씀드리면/말씀드릴게요” 도입부를 제거합니다. maxLength·ellipsis에 lengthUnit: "code-points"를 더하면 이모지를 중간에서 자르지 않습니다. wordBoundaryMinLength는 잘린 문자열의 마지막 공백이 지정한 UTF-16 위치 이상일 때 그 공백에서 자릅니다. titleTemplateMaxLength는 사이트 접미사를 붙인 자동 제목이 이 UTF-16 길이를 넘을 때 원래 자동 제목을 유지합니다. 직접 입력한 SEO 문구에는 이 변환을 적용하지 않습니다.
공유 이미지 자동값은 대표 이미지 → 선언한 본문 첫 이미지·이전 이미지 순입니다. useFeaturedImage: false 또는 분류의 useTermImage: false로 기존 화면에서 사용하지 않던 콘텐츠 이미지를 제외할 수 있습니다. defaultRules.defaults는 콘텐츠 값이 없을 때 사용할 코드 기본값으로, 사이트 공통값보다 먼저 적용됩니다. 글에 고정 공유 이미지를 쓰려면 useFeaturedImage: false와 defaults.ogImage를 함께 선언하고 본문·이전 이미지 규칙은 켜지 않습니다. defaultRules.fallback은 사이트 공통값 뒤에 적용됩니다.
SDK 0.70.0부터 글의 공개 영상 필드를 이미지 자동값으로 연결할 수 있습니다.
videoThumbnail: { source: "youtube", field: "video_url", when: { field: "content_format", equals: "media" } }를
등록하고 FRONT에도 같은 규칙과 fields: post.fields를 전달합니다. 이 옵션을 선언한
모델은 안전한 절대 HTTPS 대표 이미지 → 조건에 맞는 YouTube 썸네일 → 기존
본문·이전 이미지 → 코드·사이트 기본값 순으로 계산합니다. 대표 이미지가 HTTP·상대
주소·인증정보 포함 URL이면 영상 후보를 사용하며, 수동 SEO 이미지에는 이 변환을
적용하지 않습니다. 옵션 없는 모델의 기존 이미지 처리는 유지됩니다.
YouTube 입력은 인증정보·공백·제어문자·역슬래시 없는 HTTPS URL만 받습니다.
youtu.be/<id> 또는 youtube.com·www.youtube.com·m.youtube.com의
watch?v=<id>·shorts/<id>·embed/<id>에서 영문·숫자·_·-로 된 11자 ID만
읽고 https://i.ytimg.com/vi/<id>/hqdefault.jpg를 만듭니다. 시작 시각은 이미지에
영향을 주지 않습니다. 임의 호스트·이미지 URL 형식은 선언할 수 없습니다.
카드에서도 같은 자동 썸네일이 필요하면 core의
metadataVideoThumbnail(rule.videoThumbnail, post.fields)를 사용합니다.
영상·조건·같이 선언한 텍스트 토큰은 공개 필드 투영을 사용하며 비공개 필드나
원본 ACF를 넘기지 않습니다. 글 자동값 전용 옵션이며 분류에는 선언하지 않습니다.
검색 차단을 유지해야 하는 동적 모델은 defaultRules[modelKey].robots: { forceNoindex: true, forceNofollow: true }를 선언하고 같은 robots를 resolveMetadata나 페이지 빌더에 전달합니다. 직접 입력한 false로 이 제한을 해제할 수 없습니다. 기존 모델 소속과 실제 FRONT 분류 경로가 다른 경우 metadata.terms.archivePaths: { notice: "/blog/:slug" }처럼 등록 모델별 내부 경로를 선언합니다. 이 값은 메타데이터 조회·편집·재검증 주소만 맞추며 공개 라우트나 콘텐츠 소속을 변경하지 않습니다. 마지막 :slug 하나만 지원합니다.
fetchCategoryCounts는 API의 category_index_activated를 categoryIndexActivated로 보존합니다. 색인 전환을 요구하는 계약에서는 이 값이 true일 때만 hubPromoted 기반 정책을 적용하고 이전 정책은 그때까지 유지합니다. 분류 메타데이터 조회에도 tags: [METADATA_CACHE_TAG]를 전달할 수 있습니다.
조회에는 METADATA_CACHE_TAG, SITE_METADATA_DEFAULTS_CACHE_TAG, routeMetadataCacheTag(routeKey, locale)가 자동 부착됩니다. 기본 재조회 주기는 300초이며 revalidate로 조정할 수 있습니다. 기존 서명 theme.updated와 createRevalidateRoute가 공통 메타데이터 태그·루트 layout·영향 경로를 무효화합니다. 수신부에 (tag) => revalidateTag(tag, { expire: 0 })를 전달해야 합니다. 공개 읽기·SSR·Proxy에는 요금제 조건을 넣지 마세요.
사이트맵도 같은 최종 noindex·대표 경로 정책을 사용하고 활성 리다이렉트 출발 주소를 제외해야 합니다. 목록의 페이지 번호·필터별 정책은 사이트 라우트에서 계산합니다. 메타데이터 저장 성공·웹훅 수신 성공·실제 HTML 반영 확인은 서로 다른 상태입니다.
사이트가 공개 페이지의 색인을 관리할 때
공개 페이지 전체를 검색에 허용하는 사이트는 robots.forceIndex: true를 선언합니다.
고정 경로는 metadata.routes[].robots, 글·분류는 해당 모델의
metadata.posts.defaultRules[modelKey].robots와
metadata.terms.defaultRules[modelKey].robots에 같은 정책을 등록합니다.
FRONT의 resolveMetadata·buildPageMetadata와 사이트맵 필터에도 이 robots를
전달해야 합니다. 개별 seo.noindex나 분류의 hub_promoted를 일괄 수정하지 않습니다.
forceIndex는 개별 검색 제외·기본값보다 우선하지만 forceNoindex보다 우선하지
않습니다. 미리보기, 미발행 글, 콘텐츠 검수 조건과 빈 목록의 필수 제외는 계속 적용됩니다.
ContentPolicy도 같은 규칙으로 수동 제외를 해석합니다. 관리자에는 사이트 정책으로
검색 허용이 표시되며 개별 검색 제외 입력은 잠깁니다. 연결 미확인 상태는 검색 허용으로
표시하지 않습니다. 이 표시는 검색엔진이 이미 페이지를 색인했다는 뜻이 아닙니다.
새 정책을 사용하는 소비자는 이를 지원하는 SDK로 먼저 배포한 뒤 콘텐츠 계약을
동기화하고 설치 확인을 갱신합니다. robots를 직접 복사할 때 일부 키만 골라 정책을
누락하지 마세요. CMS 페이지 예제는 정책을
그대로 받는 선택 인자를 제공합니다.
동적 콘텐츠의 공개·색인 정책
SDK 0.69.0의 ContentPolicy·ContentQuery는 @roottale/cms-core에서 제공합니다.
배포 계약의 metadata.posts.contentPolicies[modelKey]와 FRONT가 같은 선언을
사용하면, 현재 공개 필드·본문·경로를 기준으로 글과 목록을 다시 평가합니다.
visibility를 통과한 글만 화면에 표시하고, indexing까지 통과한 글만 검색에
허용합니다. 결과의 visible과 indexable은 별개이며 robots를 메타데이터
빌더에 전달해야 직접 설정한 noindex: false가 강제 제한을 풀지 못합니다.
관리자·공개 메타데이터 응답의 robots.noindexReasons는 같은 공통 스키마로
검증한 차단 사유 코드입니다. robots 전체를 보존해 전달하고, 사유 코드로
강제 제한을 해제하지 마세요. version은 정책 의존 값이 포함될 수 있는
불투명 문자열이므로 그대로 전달하며 숫자로 변환하거나 증가시키지 않습니다.
import type { ContentPolicy, ContentQuery } from "@roottale/cms-core";
// 아래 필드는 활성 공개 필드 그룹에 선언되어 있어야 합니다.
export const contentPolicies = {
blog: {
visibility: [
{ field: "active", op: "notEquals", value: false },
{ field: "content_format", op: "oneOf", values: ["article"], allowEmpty: true },
{ op: "bodyContent", allowExcerpt: true },
],
indexing: [
{ op: "bodyText" },
{ field: "reviewer_name", op: "text" },
{ field: "reviewed_at", op: "date" },
{ field: "sources", op: "some", checks: [
{ field: "label", op: "text" },
{ field: "url", op: "safeHttps" },
] },
],
},
} satisfies Record<string, ContentPolicy>;
export const blogQuery = {
modelKeys: ["blog"], pinnedField: "pinned", pageSize: 12,
} satisfies ContentQuery;
등록 위치는 글 정책이 metadata.posts.contentPolicies, 고정 목록이
metadata.routes[].contentQuery, 분류별 목록이 metadata.terms.contentQueries[modelKey]입니다.
쿼리가 참조하는 모든 모델에는 글 정책이 있어야 하며, 선언한 posts.modelKeys와
terms.modelKeys의 범위를 지킵니다. 본문 페이지(source.kind: "page")에는
목록 쿼리를 붙이지 않습니다. 기존 정책·쿼리 없는 계약의 동작은 유지됩니다.
필드 검사는 equals·notEquals·oneOf·text·date·safeHttps·allowedPath와
한 단계 repeater의 some만 지원합니다. when: { field, equals }로 특정 값일 때만
검사할 수 있습니다. SDK 0.70.0부터는 when: { all: [...], unlessAll: [...] }도
지원합니다. all은 조건이 모두 일치해야 하고, unlessAll은 조건이 모두 일치할
때만 검사를 생략합니다. 두 그룹 중 하나 이상을 선언하며 각 그룹은 equality 조건
1~4개만 받습니다. 빈 그룹·중첩·단일 조건과 그룹의 혼합은 허용하지 않습니다.
조건의 필드도 공개 필드 64개 한도에 포함합니다. visibility·indexing 각각의
검사 24개 한도는 그대로입니다. all과 unlessAll을 함께 쓰면 두 제한을 모두
충족해야 합니다. 누락·null은 명시적인 false와 같지 않습니다.
임의 함수·정규식·중첩 repeater·관계형 값은 정책 입력이 아닙니다.
post.fields의 공개 값만 사용하고 비공개 ACF를 전달하지 마세요. 누락 값은
undefined이며 notEquals: false는 누락도 통과합니다. oneOf의
allowEmpty: true는 누락·null·빈 문자열·false·0도 허용하므로 필수 필드에는
해당 옵션을 사용하지 않습니다.
예를 들어 방송 기록을 content_format === "media"·broadcast_record === true·
medical_content === false인 경우로 한정한다면, 다음 조건들을 같은 전체 정책의
검수·출연자·출처 검사에 연결합니다. 예외일 때만 일부 검사를 생략하고, 출처 필수와
강제 검색 제외는 유지합니다. 이 조건 선언만으로 글을 공개하지는 않습니다.
// 실행 예제 lib/content-policy.ts가 같은 조건을 제공합니다.
const record = [
{ field: "content_format", equals: "media" },
{ field: "broadcast_record", equals: true },
{ field: "medical_content", equals: false },
];
const reviewWhen = { unlessAll: record };
const performerWhen = {
all: [{ field: "content_format", equals: "media" }], unlessAll: record,
};
const recordSourcesWhen = { all: record };
// indexing에 추가하면 예외 방송 기록은 수동 noindex:false로 풀 수 없습니다.
const recordNoindexCheck = {
field: "broadcast_record", op: "notEquals", value: true,
when: { all: [
{ field: "content_format", equals: "media" },
{ field: "medical_content", equals: false },
] },
};
bodyContent는 표시 가능한 HTML 또는 JSON 텍스트를 확인하고, 명시한 경우에만
요약·대표 이미지·additionalUrl을 대체 콘텐츠로 허용합니다. bodyText는 사용할
HTML이 있으면 그 텍스트를, 없으면 JSON의 text 노드를 읽습니다. 이미지뿐인
본문은 텍스트 검사를 통과하지 않습니다. 본문 소스 선택은 core의
resolvePostBodySource로 공유하며 기존 renderer/server의 같은 export도 유지됩니다.
evaluateContentPolicy를 직접 부를 때는 expectedPath에
resolvePostPublicPath(post, modelContext) 결과를 반드시 전달합니다. null도
그대로 전달하며 post.path 자체를 넣지 않습니다. modelContext에는 현재 모델의
presentation·호환 컬렉션·전체 분류가 필요합니다. 발행 상태·발행일·대표 경로와
모델 경로가 맞는지도 평가하므로, 임의로 만든 경로로 잘못된 글을 통과시키지 않습니다.
실행 예제 examples/nextjs/lib/content-policy.ts는 모든 커서를 수집하고 같은
평가 결과를 재사용합니다. 다음 코드의 contextFor에는 위 모델 정보를 돌려주는
사이트 함수를 전달합니다.
import { evaluateContentQuery, type PublicPathContext } from "@roottale/cms-core";
import { fetchAllContentPolicyPosts, evaluateContentPolicyPosts,
type PolicyPost } from "@/lib/content-policy";
// 위 contentPolicies와 blogQuery를 같은 사이트 모듈에서 가져옵니다.
async function loadBlogPage(
apiKey: string,
page: number,
contextFor: (post: PolicyPost) => PublicPathContext,
) {
const posts = (await Promise.all(blogQuery.modelKeys.map((modelKey) =>
fetchAllContentPolicyPosts({ apiKey, modelKey, locale: "ko" }),
))).flat();
const candidates = evaluateContentPolicyPosts(posts, contentPolicies, contextFor);
const listing = evaluateContentQuery(blogQuery, candidates, { complete: true, page });
return { listing, candidates };
}
첫 100건만 읽은 결과에 complete: true를 붙이지 마세요. 모든 모델의 마지막
커서까지 성공한 뒤에만 완전한 입력입니다. complete: false는 예외이며 네트워크
실패·커서 누락도 빈 목록이나 noindex 성공으로 바꾸지 않습니다.
쿼리는 공개 가능한 글 → 모델·필터·범위 선택 → pinnedField === true 우선 →
발행일 내림차순·ID 오름차순 → 현재 페이지 순으로 계산합니다. 목록의 색인 여부는
현재 페이지 안에 색인 가능한 글이 있는지로 정합니다. 본문은 listing.items,
메타데이터는 같은 listing.robots를 사용하세요. filters는
equals·notEquals·oneOf, scope는 currentTerm(분류 ID 필수) 또는
currentPath(현재 목록 경로 필수)만 지원합니다. 여러 목록을 평가할 때에는 필요한
모델의 합집합을 한 번 수집하고 candidates를 재사용할 수 있습니다.
빈 분류가 실제로 404인 사이트만 분류 쿼리에 requireItems: true를 선언합니다.
일반 목록의 빈 첫 페이지는 visible: true, indexable: false이므로 200 화면을
유지합니다. 범위를 벗어난 페이지는 visible: false입니다. 고정 목록에는
requireItems: true와 scope: "currentTerm"을 선언할 수 없습니다. 관리자 목록
메타데이터와 사이트맵은 첫 페이지, FRONT는 요청받은 페이지 번호로 평가합니다.
사이트맵도 candidates의 글 정책과 같은 목록 쿼리를 사용하고 최종 수동 SEO·강제
robots·canonical·리다이렉트 제외 규칙을 함께 적용합니다. 기존 createSitemapIndex
팩토리가 등록 정책을 자동으로 가져오지는 않으므로 정책을 쓰는 사이트의 사이트맵
수집 코드에도 연결하세요. selectContentQuery는 글 정책과 목록 평가를 한 번에
호출하는 편의 API이며, 여러 화면에서 재사용할 때는 위처럼 두 평가를 분리합니다.
캐시 연결은 발행 웹훅 문서의 공개 정책 절을 따릅니다.
관리 API·MCP
CLI도 같은 관리 API를 사용합니다. rt cms metadata list --site-id <site-id> --kind route --state custom, rt cms metadata get route home --site-id <site-id>로 조회합니다. 수정은 rt cms metadata update route home --site-id <site-id> --input-file patch.json이며 파일에는 { "expected_version": "직전 조회값", "patch": { "title": null } }처럼 실제 변경만 넣습니다. 인증키를 명령 인자에 넣지 마세요.
코드에 있는 최후 기본 공유 이미지는 경로 계약의 fallback.ogImage로 선언합니다. 페이지 자체 이미지에 해당하는 defaults.ogImage와 구별하면 사이트 공통 공유 이미지가 먼저 적용되고, 공통 이미지까지 없을 때 코드 fallback을 사용합니다. 공개 경로 응답의 fallback도 빌더에 그대로 전달합니다.
설치 확인 표식의 체크섬은 metadataContractChecksum(normalizedContract)로 계산할 수 있습니다(@roottale/cms-client/server). 이 함수는 배포 도구가 정규화해 등록한 manifest를 입력받아 재귀 키 정렬과 SHA-256만 수행합니다. 스키마 검사나 생략된 기본값 채우기는 하지 않습니다. 등록 API와 사이트가 같은 정규화된 계약을 사용해야 하며 입력 JSON이 다르면 설치 확인이 실패합니다. 첫 설치에서 경로 설정이 아직 없으면 verification.version은 생략하고 routeKey·locale·contractChecksum을 전달합니다.
filterMetadataSitemapEntries(entries, policyFor, { redirects })는 이미 읽은 메타데이터와 fetchRedirects의 활성 규칙을 사용해 사이트맵을 거릅니다. policyFor(entry)는 { metadata: SSR에_사용한_입력, canonical: 최종_대표주소, published: true }를 반환합니다. 미확인 설정은 기존 포함을 유지하며, 최종 noindex·비공개·다른 대표 주소·활성 이동 출발 주소를 제외합니다. 함수가 네트워크를 대신 조회하지는 않습니다.
listCmsMetadata → getCmsMetadata → updateCmsMetadata 순서로 지원 필드와 현재 version을 확인하고 변경합니다. PATCH는 expected_version과 patch를 받습니다. 필드 미전송은 유지, null은 자동값 복귀, 불리언 false는 그대로 저장됩니다. 오래된 버전은 409로 거절합니다. 임의 canonical·HTML 입력은 제공하지 않습니다. 역할·API scope·Pro·연결 검사는 서버가 수행하며 다른 API 경로로 우회할 수 없습니다.
사이트맵
createSitemapIndex는 사이트맵 인덱스(/sitemap.xml)와 섹션별 하위 사이트맵
(/sitemap/static.xml·/sitemap/blog.xml·/sitemap/categories.xml)을 만듭니다.
하나의 거대한 파일 대신 섹션별로 나뉘어 검색엔진이 더 잘 크롤하고, 50,000 URL/50MB
한도에도 안전합니다. 발행 글·카테고리는 자동 포함됩니다.
// app/sitemap.ts
import { createSitemapIndex } from "@roottale/cms-renderer-next/routes";
const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL!;
const { generateSitemaps, sitemap } = createSitemapIndex(
{
apiKey: process.env.ROOTTALE_API_KEY!,
apiBase: process.env.ROOTTALE_API_BASE,
siteUrl: SITE_URL,
title: "예시 사이트",
},
[
// 정적 경로 — 발행 글·카테고리 URL은 자동 추가됨
{ url: SITE_URL },
{ url: `${SITE_URL}/blog` },
{ url: `${SITE_URL}/contact` },
],
{
// 사이트에 실제로 존재하는 라우트와 콘텐츠에 맞춰 코드에서 결정합니다.
blogImages: true,
authors: false,
},
);
// Next 16: 인덱스를 만들려면 generateSitemaps·default 를 둘 다 export.
export { generateSitemaps };
export default sitemap;
- 블로그 이미지 색인 — 글에 대표 이미지가 있으면
<image:image>로 함께 색인할지 사이트 코드의blogImages로 정합니다. - 분류·작가 모음 페이지는 기본으로 사이트맵에서 빠집니다 — 어드민에서 "검색에 노출"을 켠 것만 들어갑니다. 아래 "색인 위생" 절을 보세요.
changeFrequency/priority는 Google이 무시하므로 더 이상 내보내지 않습니다(loc+lastmod+ 이미지만).- 단일 평면 사이트맵이 필요하면 레거시
createSitemap(default export 하나)도 그대로 동작하지만, 신규 사이트는createSitemapIndex를 권장합니다.
작가 아카이브 (/blog/author/{slug})
어드민 설정 > 팀에서 작가에게 주소(slug)를 발급하고 사이트 프로젝트에 실제 작가
모음 라우트를 만든 뒤, createSitemapIndex 옵션의 authors: true를 지정하면 작가
사이트맵(/sitemap/authors.xml)이 추가됩니다. 라우트가 없으면 반드시 false로 둡니다.
// app/blog/author/[slug]/page.tsx
import { notFound } from "next/navigation";
import { fetchAuthors, profilePageSchema } from "@roottale/cms-client/server";
import { RootTaleBlogList } from "@roottale/cms-renderer-next/server";
const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL!;
export default async function AuthorArchive({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { slug } = await params;
const authors = await fetchAuthors({ apiKey: process.env.ROOTTALE_API_KEY! });
const author = authors.find((a) => a.slug === slug);
if (!author) notFound();
const jsonLd = profilePageSchema({
url: `${SITE_URL}/blog/author/${slug}`,
name: author.name,
image: author.imageUrl,
description: author.bio,
});
return (
<>
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
/>
<h1>{author.name}</h1>
{author.bio ? <p>{author.bio}</p> : null}
{/* author= 로 그 작가의 발행 글만 렌더 */}
<RootTaleBlogList apiKey={process.env.ROOTTALE_API_KEY!} author={slug} />
</>
);
}
fetchAuthors()는 slug가 있고 발행 글이 1건 이상인 작가만 반환합니다 (GET /v1/cms/public/authors).RootTaleBlogList에author={slug}를 주면 그 작가의 글만 가져옵니다 (GET /v1/cms/public/posts?author={slug}).- 글 상세의
articleSchema에authorUrl: ${SITE_URL}/blog/author/${post.authorSlug}를 넘기면 글의 author 엔티티가 이 작가 페이지의ProfilePage.mainEntity와 같은@id({authorUrl}#person)로 연결됩니다.
카테고리 허브 (/blog/categories/{slug})
RootTaleBlogList의 카테고리 칩, RootTaleBlogCategories, RootTaleBlogPost
의 breadcrumb 카테고리 세그먼트가 모두 기본적으로 /blog/categories/{slug}
를 링크합니다(defaultCategoryHref) — 단일 블로그 사이트도 이 라우트를
구현해야 링크가 404 나지 않습니다. 참조 구현은 예시 코드
app/blog/categories/[slug]/page.tsx(MCP tool readRootTaleNextjsExampleCode).
공지·블로그처럼 섹션을 나눈 사이트는 {basePath}/categories/{slug} 패턴
(collections.md "URL이 어떻게 정해지나" 절)을 대신 씁니다.
목록 페이지용 JSON-LD는 collectionPageSchema:
import { collectionPageSchema } from "@roottale/cms-client/server";
const jsonLd = collectionPageSchema({
url: `${SITE_URL}/blog/categories/${category.slug}`,
name: `${category.name} 글 모음`,
siteUrl: SITE_URL,
});
색인 위생 — 모음 페이지는 기본 "검색 노출 안 함"
분류·태그·작가·검색 결과처럼 글을 모아 보여주는 페이지는 내용이 겹치기 쉬워, 전부 검색에 올리면 오히려 사이트 평가가 내려갑니다. 그래서 RootTale은 모음 페이지를 기본으로 검색에서 빼고, 소개 글을 채워 대표로 삼은 분류만 올립니다.
- 켜는 곳: 어드민 내 사이트 > 카테고리에서 분류를 펼치고 "검색에 이 분류 페이지
노출"을 체크합니다. 켠 분류만 사이트맵에 들어가고
robots도 색인 허용이 됩니다. - 작가 모음은 프로젝트에 실제 라우트가 있을 때만 사이트 코드에서
authors: true로 같은 결정을 내립니다. - 글 자체는 영향을 받지 않습니다 — 모음 페이지만 빠집니다.
판정은 decideArchiveIndex 하나에서 나옵니다. 사이트맵 필터와 페이지의 robots가
같은 함수를 보므로 "검색에서 빼기로 해놓고 사이트맵에는 넣는" 어긋남이 생기지
않습니다. 단, 같은 함수를 쓰는 것만으로는 부족하고 판정에 넣는 값도 같아야
합니다. 그래서 입력을 만드는 세 가지도 함께 제공합니다:
resolveCategoryPromotion(slugs, slug)— 노출 설정을 3단계 (promoted/not-promoted/unknown)로 바꿉니다. 설정을 못 읽었을 때unknown을 그대로 넘기면 정책이 기존 상태를 보존합니다. 여기서 임의로 "안 켬"으로 바꾸면, 설정 조회가 한 번 실패했다는 이유만으로 이미 검색에 올라가 있던 주소에 noindex 가 붙습니다.fetchBlogArchiveCategories(config)—/blog분류 모음 페이지가 다루는 글 에서 분류와 글 수를 뽑습니다. 사이트맵도 같은 함수를 씁니다. 직접 글을 받아 세지 마세요 — 세는 글 집합이 갈리면 "사이트맵엔 주소가 있는데 페이지는 404" 가 생깁니다.ARCHIVE_POST_COUNT_LIMIT— 아래 폴백 경로가 쓰는 글 개수 한도. 직접 셀 때도 같은 상수를 쓰세요.
글 수는 GET /v1/cms/public/categories 가 서버에서 세어 내려줍니다. 글이
몇 건이든 모든 분류의 정확한 개수가 나오므로, 오래된 글에만 달린 분류가 검색에서
사라지지 않습니다. fetchBlogArchiveCategories 가 이 API를 먼저 쓰고, 못 받으면
(구버전 API이거나 일시 장애) 예전처럼 최근 글 ARCHIVE_POST_COUNT_LIMIT 건을 받아
세는 방식으로 되돌아갑니다 — 사이트맵과 페이지가 여전히 같은 함수를 쓰므로 어느
경로든 두 곳의 결론은 같습니다.
어떤 글을 세나요:
/blog계열 모음 페이지는 "콘텐츠 유형(스트림)에 속하지 않은 글"만 다룹니다. 증상·질환 같은 별도 유형을 쓰는 사이트에서 그 유형 글에만 달린 분류는/blog/categories/{slug}로 볼 수 없으므로(그 유형은 자기 주소가 따로 있습니다) 사이트맵에서도 빠집니다.fetchBlogArchiveCategories가 이 범위를 서버에 물어보므로(exclude_collections), 어떤 유형을 만들었든 두 곳이 항상 같은 글을 셉니다. 유형별 모음 페이지({유형주소}/categories/{slug})는collectCollectionCategories(posts, collections, key)가 짝입니다.
// app/blog/categories/[slug]/page.tsx
import { notFound } from "next/navigation";
import {
buildArchiveMetadata,
decideArchiveIndex,
fetchBlogArchiveCategories,
resolveCategoryPromotion,
} from "@roottale/cms-renderer-next/routes";
import { fetchBlogSettings } from "@roottale/cms-client/server";
const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL!;
const apiKey = process.env.ROOTTALE_API_KEY!;
async function archiveState(slug: string) {
const [settings, categories] = await Promise.all([
// 설정 조회 실패는 "안 켬"이 아니라 "모름"입니다 — undefined 로 넘깁니다.
fetchBlogSettings({ apiKey }).catch(() => null),
// 사이트맵과 같은 함수 = 같은 글 집합, 같은 한도.
fetchBlogArchiveCategories({ apiKey }),
]);
return {
promotion: resolveCategoryPromotion(
settings?.sitemap?.promotedCategorySlugs,
slug,
),
// 이 라우트가 모르는 분류면 0건 → 아래에서 404.
postCount: categories.find((c) => c.slug === slug)?.count ?? 0,
};
}
export async function generateMetadata({ params }) {
const { slug } = await params;
const { promotion, postCount } = await archiveState(slug);
return buildArchiveMetadata(
{ kind: "category", promotion, postCount, title: `${slug} 글 모음` },
{ siteUrl: SITE_URL, path: `/blog/categories/${slug}` },
);
}
export default async function CategoryArchive({ params }) {
const { slug } = await params;
const { promotion, postCount } = await archiveState(slug);
// 글이 하나도 없는 모음 페이지는 만들지 않습니다(404).
if (decideArchiveIndex({ kind: "category", promotion, postCount }).render === "notFound") {
notFound();
}
// ... 목록 렌더
}
정책 요약(decideArchiveIndex):
| 상황 | 화면 | 검색 노출 | 사이트맵 |
|---|---|---|---|
| 글 0건 (검색 결과 제외) | 404 | ✕ | ✕ |
| 2페이지 이상 | 정상 | ✕ | ✕ |
| 태그·날짜·사이트 내 검색 | 정상 | ✕ | ✕ |
분류·작가 — 노출 켬(promoted) | 정상 | ○ | ○ |
분류·작가 — 노출 끔(not-promoted, 기본) | 정상 | ✕ | ✕ |
분류·작가 — 설정 모름(unknown) | 정상 | ○ | ○ |
승격 목록은 GET /v1/cms/public/blog-settings 응답의
sitemap.promoted_category_slugs(cms-client에서는 sitemap.promotedCategorySlugs)
로 내려옵니다. 이 필드가 아예 없는 구버전 API에 붙어 있거나 설정 조회에 실패하면
resolveCategoryPromotion 이 unknown 을 돌려주고, 렌더러는 정책을 적용하지 않고
기존처럼 모든 분류를 사이트맵에 넣습니다(모른다고 이미 색인된 주소를 지우지 않기
위해서입니다). 빈 배열 [] 은 "승격 0건"이라는 확정 정보라 의미가 다릅니다.
구버전 클라이언트 호환: sitemap.promoted_category_slugs 는 응답에 새로 생긴
키입니다. @roottale/cms-client 는 응답에서 아는 필드만 골라 쓰고 모르는 키는
무시하므로(스키마 전체 검증을 하지 않습니다) 구버전 사이트를 그대로 두어도 이 키
때문에 깨지지 않습니다 — 사이트를 올리지 않으면 이 절의 색인 정책이 적용되지 않을
뿐입니다.
한도 안내: 분류별 글 수는
GET /v1/cms/public/categories가 서버에서 세므로 글이 아무리 많아도 누락되지 않습니다. 다만 그 API를 못 받아 폴백으로 도는 동안 (구버전 API·일시 장애)에는 최근ARCHIVE_POST_COUNT_LIMIT건만 보게 되어, 한도 밖에만 글이 있는 분류가 사이트맵과 페이지 양쪽에서 빠집니다(페이지는 404). 양쪽이 같은 기준으로 판단하므로 색인 어긋남은 이때도 생기지 않습니다.유형별 모음 페이지(
{유형주소}/categories/{slug})를 만드는collectCollectionCategories는 아직 최근 글 배치만 씁니다. 서버 집계 API는collection_key로 유형 범위를 지정할 수 있으므로 같은 방식으로 옮길 예정입니다.
어긋남이 잠깐 보일 수 있는 경우: 사이트맵과 모음 페이지는 서로 다른 요청에서 각자 설정을 읽습니다. 한쪽만 조회에 실패하면 그 사이에는 "검색에서 뺐는데 사이트맵엔 남아 있는" 상태가 생길 수 있습니다. 사이트맵이 다시 만들어질 때 자동으로 맞춰지며, 걸리는 시간의 상한 = 사이트맵의
revalidate값입니다 (Site Kit 기본 60초). 조회 실패 때 주소를 빼지 않고 남기는 쪽을 택한 이유는, 일시적인 장애 한 번으로 이미 검색에 올라간 주소를 사이트맵에서 지우는 손실이 더 크기 때문입니다.
다국어 (hreflang) — ADR-0052 A안, 콘텐츠 다국어
번역 글이 있는 사이트는 어드민 설정 > 블로그 > 사이트맵의 "다국어 로케일"에
언어 코드를 입력합니다(예: ko, ja, en, 첫 번째 = 기본 locale). 사이트맵의
blog 섹션(GET /sitemap/blog.xml)이 글 단위 실제 번역 데이터로 hreflang
대체 언어 링크(<xhtml:link rel="alternate">)를 계산합니다:
- 공개 API(
GET /v1/cms/public/posts)가 글마다translations(발행된 언어판 목록, 자기 자신 포함)를 내려줍니다. 언어판이 없는 글(자기 자신 1건뿐)은 hreflang alternates 자체가 생략됩니다 — 존재하지 않는 URL 을 검색엔진에 알리는 사고를 원천 차단합니다(옛 slug 1:1 path-prefix 가정 제거). - 기본 locale = prefix 없는 경로 +
x-default. 나머지는 경로 접두사 (ko가 기본이면ja언어판은/ja/blog/{그-언어판-실제-slug}) — 언어판마다 독립된 slug를 가질 수 있습니다(동일 slug 강제 아님). - 실제 번역 라우트를 그 경로(
/ja/...)에 서빙하는 것은 사이트 쪽 책임 입니다 — starter 참조 구현은app/[locale]/blog/·app/[locale]/blog/[slug]/·app/[locale]/[slug]/(기본 locale 은 prefix 없는 기존 경로 그대로). static/categories/authors섹션은 hreflang alternates 를 붙이지 않습니다 — v1 은 블로그 글 + CMS[slug]페이지만 번역 대상이라(nav 정적 경로·카테고리 아카이브·작가 아카이브는 locale 라우트 자체가 없음), 옛 방식대로 path-prefix 를 씌우면 존재하지 않는 URL 의 hreflang 이 됩니다.- 로케일을 비워두면(또는 기본 locale 조차 발행 글 0건이면) 단일 언어로 동작합니다(alternates 미부착, fail-closed).
글 상세 <head> hreflang 은 buildPostMetadata(아래 "글 메타데이터" 절 참고)의
locales/translations 옵션으로 계산합니다 — 사이트맵과 같은 원본 데이터
(translations[])를 씁니다.
다중 스트림 (collections) — 공지·블로그 분리
같은 글 풀을 공지 게시판(/notice) + 블로그(/blog) 등 여러 섹션으로 나눠 서로 다른
URL·레이아웃으로 보여줄 수 있습니다. 섹션은 글의 collection_key로 정해지고, 카테고리는
섹션 안의 주제(아카이브)입니다. URL 구조·어드민 설정·연동 코드(코드 상수 vs 어드민
fetch)·가드·동적 basePath는 별도 문서 콘텐츠 유형 (Collections)
에 정리되어 있습니다. 여기 sitemap/feed 예시도 collections를 넘기면 섹션별로 파생됩니다.
robots.txt
크롤링 제어의 기본. sitemap 위치를 알려주고, 크롤링이 무의미한 경로만 차단합니다. CSS/JS/이미지 경로를 차단하지 마세요 — 구글이 페이지를 렌더링하지 못해 평가가 깨집니다. 색인 제외가 목적이면 robots.txt 차단이 아니라 페이지의 noindex 를 쓰세요 (외부 링크가 있으면 차단해도 색인될 수 있습니다).
// app/robots.ts
import type { MetadataRoute } from "next";
const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL!;
export default function robots(): MetadataRoute.Robots {
return {
rules: [{ userAgent: "*", allow: "/", disallow: ["/api/"] }],
sitemap: `${SITE_URL}/sitemap.xml`,
};
}
새 글 발견 알림: WebSub와 IndexNow
사이트맵은 전체 URL 목록의 원장이고, 발행 직후 알림은 보조 수단입니다. 일반 블로그
글에는 Google Indexing API를 쓰지 마세요. 이 API는 JobPosting과
BroadcastEvent가 포함된 라이브 스트림 페이지에만 허용됩니다.
createFeedRoute에 webSubHubUrl을 주면 RSS에 rel="hub"와 기존
rel="self"가 함께 들어갑니다.
export const GET = createFeedRoute({
apiKey: process.env.ROOTTALE_API_KEY!,
siteUrl: process.env.NEXT_PUBLIC_SITE_URL!,
title: "사이트 블로그",
webSubHubUrl: "https://pubsubhubbub.appspot.com/",
});
IndexNow는 Bing·Naver 등 참여 검색엔진용이며 Google 색인 요청이 아닙니다. 소유권
확인을 위해 같은 host의 공개 키 파일이 필요합니다. Site Kit은
INDEXNOW_KEY가 설정된 경우 /indexnow-key.txt에서 그 키만 반환합니다. 플랫폼이
보낸 알림의 200·202 응답은 “접수됨”을 뜻하며 검색결과 노출을 보장하지 않습니다.
브레드크럼 (BreadcrumbList)
사이트 구조를 검색엔진에 전달하고 검색결과에 경로가 표시됩니다.
빠른 경로 — RootTaleBlogPost 를 쓰면 breadcrumb prop 하나로 시각
브레드크럼 + BreadcrumbList JSON-LD 를 함께 얻습니다(opt-in, 기본 off):
<RootTaleBlogPost
apiKey={apiKey}
slugOrId={slug}
breadcrumb={{ siteUrl: SITE_URL }} // siteUrl 없으면 시각 브레드크럼만
/>
카테고리 세그먼트는 글의 첫 category term 을 자동으로 쓰고
(showCategory: false 로 생략 가능), 링크는 defaultCategoryHref
(/blog/categories/{slug})를 씁니다 — blog.md "카테고리 허브 라우트" 참고.
자세한 옵션(homeLabel/listHref/categoryHref/collections 연동)은
blog.md "저자 링크 + 브레드크럼" 절 참고.
커스텀 경로 — 직접 마크업하는 경우 breadcrumbSchema 로 JSON-LD 만
생성하세요(UI 브레드크럼과 구조 일치 권장):
import { breadcrumbSchema } from "@roottale/cms-client/server";
const category = post.terms.find((t) => t.taxonomy === "category");
const crumbs = breadcrumbSchema([
{ name: "홈", url: SITE_URL },
{ name: "블로그", url: `${SITE_URL}/blog` },
...(category
? [{ name: category.name, url: `${SITE_URL}/blog/categories/${category.slug}` }]
: []),
{ name: post.title, url: `${SITE_URL}/blog/${post.slug}` },
]);
블로그 목록 페이지네이션 주의
- 마지막 페이지에 다음(next) 링크를 렌더하지 마세요 — 같은 페이지가 반복 노출되면 크롤 낭비·중복 신호가 됩니다.
- 필터·정렬로 내용이 바뀌면 URL(쿼리)도 함께 바뀌어야 하고, canonical 은 필터 없는 기본 목록을 가리키게 하세요.
- 검색결과(사이트 내 검색) 페이지는 noindex 처리하세요 — 특히 결과 0건 페이지가 색인되면 저품질(소프트 404) 신호가 됩니다.
RSS/사이트맵과 웹훅
발행 웹훅의 alsoRevalidate에 /feed.xml, /sitemap.xml을 포함해 글 변경
시 함께 갱신하세요 (revalidation-webhooks.md 참고).
메인 홈 메타데이터 (홈 제목·홈 설명)
새 연동은 홈도 위의 fetchRouteMetadata와 buildPageMetadata를 사용합니다.
기존 연동의 fetchBlogSettings().siteProfile.homeTitle / homeDescription
(공개 API site_profile.home_title / home_description)은 호환을 위해 유지합니다.
계약 등록만으로 전환하지 않고, 초기값 보존 또는 실제 설치 확인에서 홈 전환을
완료할 때까지 기존 홈 설정을 반환합니다. 전환 뒤에는 현재 소유 경로의 effective
제목·설명을 반환하며 초기화·연결 해제·계약 제거로 예전 홈 설정이 다시 나타나지 않습니다.
CMS 홈이 초안이거나 소유 경로가 제거되면 null을 반환합니다.
아래는 기존 연동용 예시입니다. 홈(/) 라우트의 generateMetadata에서
이 값을 우선 쓰고, 비어 있으면(null) 사이트
이름(fetchTheme().siteName)·사이트 설명(siteProfile.siteDescription)으로
폴백하세요. title 은 root layout 의 %s | 사이트명 템플릿을 타지 않도록
{ absolute } 로 넘깁니다. openGraph 는 page 값이 layout 값을 통째로
대체하므로 siteName·images 까지 다시 채웁니다.
// app/page.tsx
import type { Metadata } from "next";
import {
BLOG_SETTINGS_CACHE_TAG,
fetchBlogSettings,
fetchTheme,
THEME_CACHE_TAG,
} from "@roottale/cms-client/server";
const apiKey = process.env.ROOTTALE_API_KEY!;
export async function generateMetadata(): Promise<Metadata> {
const [theme, settings] = await Promise.all([
fetchTheme({ apiKey, tags: [THEME_CACHE_TAG] }).catch(() => null),
fetchBlogSettings({ apiKey, tags: [BLOG_SETTINGS_CACHE_TAG] }).catch(() => null),
]);
const siteName = theme?.siteName ?? "예시 사이트";
const profile = settings?.siteProfile;
const title = profile?.homeTitle ?? siteName;
const description = profile?.homeDescription ?? profile?.siteDescription ?? undefined;
const image = profile?.defaultOgImageUrl ?? undefined;
return {
title: { absolute: title },
description,
alternates: { canonical: "/" },
openGraph: {
type: "website",
siteName,
title,
description,
...(image ? { images: [image] } : {}),
},
};
}
어드민에서 저장하면 서버가 theme.updated 알림을 보내므로 revalidation- webhooks.md 의 태그 배선(BLOG_SETTINGS_CACHE_TAG)이 되어 있으면 홈
제목·설명이 곧바로 반영됩니다. sites/starter 는 buildHomeMetadata()
(components/SiteRootShell.tsx)로 같은 동작이 이미 배선돼 있습니다.
글 메타데이터 (canonical·robots·OG)
블로그 글 상세의 generateMetadata 에서 어드민 SEO 패널(metaJson.seo) 값을
buildPostMetadata 로 한 줄 변환합니다. canonical/robots/openGraph 분기를
직접 쓰면 한 곳이라도 빠뜨려 SEO 가 새기 쉬운데(특히 noindex 누락·canonical
미설정), 이 헬퍼로 표준화합니다.
// app/blog/[slug]/page.tsx
import type { Metadata } from "next";
import { buildPostMetadata } from "@roottale/cms-renderer-next/routes";
export async function generateMetadata({ params }: Props): Promise<Metadata> {
const { slug } = await params;
const post = await getPost(slug);
if (!post) return {};
return buildPostMetadata(post, {
siteUrl: process.env.NEXT_PUBLIC_SITE_URL, // self-canonical 기본값 origin
path: `/blog/${post.slug}`, // 현재 slug 기준
});
}
seo.title/seo.description/seo.ogImageoverride → 없으면 글 값 fallback- canonical:
seo.canonicaloverride → 없으면siteUrl+path로 self-canonical 자동 생성(모든 글이 자기 자신을 가리키는 canonical 을 갖도록 — 권장).siteUrl/path를 안 넘기면 override 가 있을 때만 canonical 출력. seo.noindex/seo.nofollow중 하나라도 켜지면robots출력openGraph(type:article·publishedTime·images) 자동 구성- avcd 구조 —
siteUrl이 있으면 canonical 해석 성공 여부와 무관하게alternates.types["application/rss+xml"](기본/feed.xml,feedPath옵션으로 override)을 항상 emit합니다.twitter(summary_large_image)도 og 와 같은 소스(seo override → 글 값)로 항상 채워집니다 —card+title은 og 이미지가 없어도 emit,images는 og 이미지가 있을 때만. - avcd 구조 — og article 확장 — 입력에
modified(→openGraph.modifiedTime)·section(→openGraph.section)·tags(문자열 배열 →openGraph.tags)·authors(저자 프로필 URL 배열 →openGraph.authors)를 넘기면 그대로 추가됩니다. 전부 선택 — 미지정/빈 배열은 생략(기존 호출부 diff 0).
return buildPostMetadata(post, {
siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
path: `/blog/${post.slug}`,
modified: post.modified, // updatedAt ISO
section: post.category || undefined,
tags: post.tags.map((t) => t.name),
authors: post.authorSlug
? [`${SITE_URL}/blog/author/${post.authorSlug}`]
: undefined,
feedPath: "/feed.xml", // 기본값 — 다중 스트림이면 섹션별 피드로 override
});
입력은 { title, description?, date?, image?, seo? } 구조면 됩니다(getPost
의 BlogPostMeta 호환). 원본 post 를 쓸 땐 seo: (post.metaJson as { seo?: PostSeoOverrides }).seo 로 넘기세요. path 는 redirect 후의 현재
slug(post.slug) 기준으로 주세요(아래 301 참고).
canonical 경로 우선순위(ADR-0105) — path 옵션 → 글의 저장된 정규 공개 경로
(post.path, 원본 post 나 path·collectionKey·modelKey 를 함께 넘기면 자동) →
collections 계산. 플랫폼이 글마다 주소를 저장해 내려주므로 사이트는 주소 규칙을
알 필요가 없습니다 — 권장 형태는 path: post.path ?? "/blog/" + post.slug 처럼
원장을 먼저 읽고 이 라우트의 기본 주소로만 폴백하는 것입니다(구 서버·주소 규칙이
없는 유형이면 post.path 가 없거나 null). storedPostPath(post) 헬퍼
(@roottale/cms-renderer-next/routes)는 소속(모델·컬렉션)이 있는 글의 저장 경로만
돌려주고, 어느 유형에도 속하지 않는 레거시 글의 /blog 폴백값은 무시합니다.
공지·블로그 다중 스트림 (ADR-0060)
섹션을 나눈 사이트(공지 /notice + 블로그 /blog)는 path 를 직접 쓰지 말고
collections 를 넘기세요. 글의 collectionKey 로 소속 섹션 basePath 를 찾아
canonical 을 공지/블로그로 구분해 해석합니다(공지 글 → /notice/{slug}, 블로그
글 → /blog/{slug}). path 를 /blog/... 로 하드코딩하면 공지 글이 잘못된
블로그 canonical 을 갖게 됩니다.
import { buildPostMetadata } from "@roottale/cms-renderer-next/routes";
import { COLLECTIONS } from "@/lib/collections"; // collections.md 참고
export async function generateMetadata({ params }: Props): Promise<Metadata> {
const { slug } = await params;
const post = await getPost(slug);
if (!post) return {};
return buildPostMetadata(post, {
siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
collections: COLLECTIONS, // collectionKey 로 /notice·/blog 자동 구분
});
}
post.collectionKey(공개 API의 collection_key)가 어느 섹션에도 안 맞으면
canonical 을 생략합니다(섹션 없는 글은 상세·sitemap에서 제외되는 규칙과 동일).
단일 블로그 사이트는 기존처럼 path: "/blog/" + post.slug 만 주면 됩니다.
원본 post 를 그대로 넘기면 post.path(플랫폼 저장 경로)가 collections 계산보다
먼저 canonical 이 됩니다 — 컬렉션 규칙이 바뀌어도 사이트 코드를 고칠 필요가 없고,
collections 는 저장 경로가 없는 글(구 서버·주소 규칙 없는 유형)의 폴백으로만 쓰입니다.
다국어 hreflang (ADR-0052 A안, W4-6 PR C1)
번역 사이트는 translations(글 응답의 translations[])와 locales 옵션을
넘기면 <head> 에 양방향 hreflang(+ x-default)이 자동으로 붙습니다:
import { buildPostMetadata } from "@roottale/cms-renderer-next/routes";
export async function generateMetadata({ params }: Props): Promise<Metadata> {
const { locale, slug } = await params; // app/[locale]/blog/[slug]/page.tsx
const post = await getPost(slug, locale);
if (!post) return {};
return buildPostMetadata(
{ ...post, translations: post.translations },
{
siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
path: `/${locale}/blog/${post.slug}`,
locales: { defaultLocale: "ko" }, // 사이트 활성 locale 의 첫 원소
},
);
}
pathFor를 안 주면 기본값기본locale → /blog/{slug},그 외 → /{locale}/blog/{slug}. 블로그가 아닌 라우트(CMS[slug]페이지 등)는pathForoverride 필수 —buildHreflangLanguages(translations, siteUrl, { defaultLocale, pathFor })를 직접 호출하면 OGtype:"article"없이 plainalternates만 조립할 수 있습니다.translations가 없거나(구 서버) 자기 자신 1건뿐(번역 없음)이면languages자체가 생략됩니다 — 단일 언어 사이트는 기존 canonical-only 동작 그대로.
slug 변경 시 301 리다이렉트
글 slug를 바꿔도 옛 URL이 깨지지 않습니다. API가 slug history로 글을 찾아 현재 slug로 응답하므로, 페이지에서 요청 slug와 비교해 301을 보내세요:
import { notFound, permanentRedirect } from "next/navigation";
import { postRedirectPath } from "@roottale/cms-renderer-next/routes";
const post = await getPost(slug);
if (!post) notFound();
const redirect = postRedirectPath(post, slug);
if (redirect) permanentRedirect(redirect);
301이어야 기존 URL의 검색 순위·백링크가 새 URL로 승계됩니다 (사이트맵·RSS는 항상 현재 slug만 포함).
동적 OG 이미지 (글별 1200×630)
글마다 제목·날짜가 들어간 소셜 공유 카드를 자동 생성합니다 — 대표 이미지를 일일이 만들지 않아도 카카오톡·페이스북·X 공유 시 글 제목이 보이는 카드가 나갑니다. 한글 제목은 Noto Sans KR 부분셋을 런타임에 받아 렌더합니다.
// 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; // { width: 1200, height: 630 }
export const contentType = OG_IMAGE_CONTENT_TYPE; // "image/png"
export default createPostOgImage(
{
apiKey: process.env.ROOTTALE_API_KEY!,
siteUrl: process.env.NEXT_PUBLIC_SITE_URL!,
title: "예시 블로그",
// 선택 — 브랜드 색 커스텀:
// backgroundColor: "#10172a", accentColor: "#38bdf8", brandLabel: "예시",
},
// Next 16 의 ImageResponse 타입은 패키지 ImageResponseLike 와 미묘하게 달라
// cast 가 필요하다(패키지는 next 비의존이라 구조적 타입만 안다).
{ ImageResponse: ImageResponse as unknown as ImageResponseLike },
);
opengraph-image.tsx파일 컨벤션이라 별도 meta 태그 없이 Next 가og:image를 자동 주입합니다 (twitter-image.tsx로 복제하면 X 카드도).- 글이 없거나 API 실패 시 사이트 제목으로 fail-soft 렌더 — 빈 카드가 나가지 않습니다.
ImageResponse는 호출부에서 주입합니다 — 본 패키지는next에 직접 의존하지 않습니다.
공개 검색 (사이트 내 검색)
searchPosts 로 발행된 글과 페이지의 통합 검색을 붙일 수 있습니다. API 키는
브라우저에 보내지 않고 Server Component나 Route Handler에서만 사용합니다:
// app/search/page.tsx (Server Component)
import {
fetchCollections,
resolveSearchHitPath,
searchPosts,
} from "@roottale/cms-client/server";
const [hits, collections] = await Promise.all([
searchPosts({
apiKey: process.env.ROOTTALE_API_KEY!,
query: q, // ?q= 쿼리
type: "all", // 글 + 페이지
locale: "ko",
limit: 20,
}),
fetchCollections({ apiKey: process.env.ROOTTALE_API_KEY! }),
]);
const links = hits.flatMap((hit) => {
const href = resolveSearchHitPath(hit, collections);
return href ? [{ hit, href }] : [];
});
// hits: { id, title, slug, excerpt, featuredImageUrl, publishedAt }[]
본문은 미포함 슬림 hit입니다. 주소를 /blog/{slug}로 직접 조립하면 공지·자료실
등 콘텐츠 유형의 실제 주소를 놓칠 수 있으므로 resolveSearchHitPath를 사용하세요.
검색결과 페이지는 위 체크리스트대로 noindex 처리를 잊지 마세요.
JSON-LD 스키마 헬퍼
@roottale/cms-client/server에서 제공:
| 함수 | 용도 |
|---|---|
articleSchema(input) | 블로그 글 상세 페이지 Article/BlogPosting |
breadcrumbSchema(items) | 빵부스러기 |
organizationSchema(input) | 조직/사업체 |
localBusinessSchema(profile, opts) | 사업장 LocalBusiness (로컬 SEO — 아래 섹션) |
websiteSchema(input) | 웹사이트 |
faqSchema(items) | FAQ |
profilePageSchema(input) | 작가 프로필 페이지 (/blog/author/{slug}) |
collectionPageSchema(input) | 글 목록/카테고리 허브 (/blog, /blog/categories/{slug}) |
import { articleSchema } from "@roottale/cms-client/server";
const jsonLd = articleSchema({
title: post.title,
description: post.excerpt,
url: `${SITE_URL}/blog/${post.slug}`,
datePublished: post.publishedAt,
image: post.featuredImageUrl ?? undefined,
});
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
/>;
avcd 구조 — 확장 옵션(전부 선택):
const jsonLd = articleSchema({
type: "BlogPosting", // 기본 "Article" — 미지정 시 기존 출력 그대로
id: `${url}#article`, // 지정 시 @id emit
headline: post.title,
url,
image: post.featuredImageUrl ?? undefined,
imageWidth: 1200, // 둘 다 있으면 image 를 ImageObject 로 승격
imageHeight: 630,
authorName: post.authorName,
authorUrl: `${SITE_URL}/blog/author/${post.authorSlug}`, // author.@id 연결
publisherName: "예시 사이트",
publisherId: `${SITE_URL}#organization`,
section: category?.name, // → articleSection
inLanguage: "ko",
});
profilePageSchema/collectionPageSchema 사용법은 각각 위 "작가 아카이브"·
"카테고리 허브" 절 참고.
저수준 RSS가 필요하면 generateRssXml / rssItemsFromPosts를 직접 사용할 수
있습니다.
로컬 SEO (네이버플레이스·구글 비즈니스)
어드민 운영 > 비즈니스 프로필에서 사업장 정보(이름·업종·주소·좌표·
영업시간·외부 프로필 URL)를 저장하면, 사이트가 fetchBusinessProfile로
조회해 LocalBusiness JSON-LD를 자동 렌더할 수 있습니다 — 주소·영업시간을
사이트 코드에 하드코딩할 필요가 없습니다.
layout에 1회 렌더하면 충분합니다:
// app/layout.tsx
import {
fetchBusinessProfile,
localBusinessSchema,
} from "@roottale/cms-client/server";
const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL!;
export default async function RootLayout({ children }) {
// 어드민에서 미설정이면 null — 렌더를 건너뛴다.
const business = await fetchBusinessProfile({
apiKey: process.env.ROOTTALE_API_KEY!,
}).catch(() => null);
return (
<html lang="ko">
<body>
{business ? (
<script
type="application/ld+json"
dangerouslySetInnerHTML={{
__html: JSON.stringify(
localBusinessSchema(business, { url: SITE_URL }),
),
}}
/>
) : null}
{children}
</body>
</html>
);
}
localBusinessSchema가 만드는 것:
@type:[업종, "LocalBusiness"](중복 제거) — 어드민에서 고른 업종 (세무·회계 =AccountingService, 병원·의원 =MedicalClinic등)address(PostalAddress) /geo(GeoCoordinates) /openingHoursSpecification/areaServedalternateName: 띄어쓰기 변형처럼 같은 사업장을 다르게 부르는 이름hasOfferCatalog: 어드민 "취급 업무" 목록 — "무엇을 하는 곳인가"를 명시하는 신호입니다. 명함·간판에 적힌 업무를 그대로 옮기면 됩니다.hasMap: 네이버플레이스 주소(없으면 카카오맵 주소)sameAs: 어드민에 입력한 네이버플레이스·구글 비즈니스 프로필·카카오 채널 등의 URL — 검색엔진이 동일 사업장임을 연결합니다. 지도 딥링크(카카오맵)는 프로필 페이지가 아니므로hasMap으로만 나가고 여기엔 포함되지 않습니다.
faxNumber는 고객이 사업장 정보에서 바꿀 수 있으며, 스타터와
localBusinessSchema가 자동으로 JSON-LD에 반영합니다. priceRange는 업종별 의미가
달라 공통 관리자·스타터가 관리하지 않습니다. 필요하면 사이트 프로젝트가
localBusinessSchema 입력에 명시적으로 추가합니다.
네이버플레이스(new.smartplace.naver.com)와 구글 비즈니스 프로필(business.google.com) 등록 자체는 공개 API가 없어 사장님이 직접 해야 하며, 어드민 화면에 등록 안내와 프로필 URL 입력란이 있습니다.
Fleet 프로브 (운영 가시성)
ROOT-ADMIN 직원용 ‘전 사이트’ 화면이 배포 버전과 보안패치 상태를 확인하는 well-known 라우트입니다. CMS 정보는 기존 SDK를 사용하고 실행 버전을 덧붙입니다.
// app/.well-known/roottale.json/route.ts
import { createFleetInfoRoute } from "@roottale/cms-renderer-next/routes";
import nextPackage from "next/package.json";
import { version as reactVersion } from "react";
const getCmsFleetInfo = createFleetInfoRoute({ site: "example" });
export const dynamic = "force-dynamic";
export const runtime = "nodejs";
export async function GET() {
const response = await getCmsFleetInfo();
return Response.json({
...await response.json(),
runtime: { next: nextPackage.version, react: reactVersion, node: process.versions.node },
}, { headers: { "cache-control": "no-store" } });
}
site에는 사이트 식별용 슬러그를 넣습니다. 필수는 아니지만 운영 지원을
받으려면 추가를 권장합니다.
기존 exposures 설정이 있으면 그대로 유지합니다. runtime.next는 설치된 정확한
버전이며 package.json의 캐럿 범위를 보내면 안 됩니다. runtime.node는 요청을
처리하는 Node.js 버전입니다. 정적 응답으로 만들면 빌드 머신의 버전이 잘못 표시될 수
있으므로 동적 실행과 no-store를 유지합니다. runtime.react는 서버 React의 버전으로,
안정판 Next.js에 포함된 React도 canary 식별자를 가질 수 있습니다. 환경 변수나 API 키는 응답에 넣지 않습니다.
실행 예제는 examples/nextjs/app/.well-known/roottale.json/route.ts에 있습니다.
관리자는 누락·오류·알 수 없는 버전을 ‘미확인’으로 표시하고 공식 공지의 보안 최소
버전과 권장 Next.js 버전을 구분합니다. 저장소 업데이트 뒤 운영 재배포까지 끝나야
새 버전이 표시됩니다. 이 점검이 사이트를 자동 업데이트하거나 배포하지는 않습니다.
AEO/GEO — llms.txt
AI 검색·생성엔진(ChatGPT·Claude·Perplexity 등)의 크롤러는 llms.txt 마크다운 인덱스로 사이트 구조와 콘텐츠를 빠르게 파악합니다. 발행 글 목록(최대 100개)을 제목·요약과 함께 자동 포함하므로, AI가 관련 질문에 답할 때 내 사이트의 글이 출처로 인용될 가능성을 높입니다(AEO/GEO).
// app/llms.txt/route.ts
import { createLlmsTxtRoute } from "@roottale/cms-renderer-next/routes";
export const dynamic = "force-dynamic";
export const GET = createLlmsTxtRoute({
apiKey: process.env.ROOTTALE_API_KEY!,
apiBase: process.env.ROOTTALE_API_BASE,
siteUrl: process.env.NEXT_PUBLIC_SITE_URL!,
title: "예시 사이트",
description: "예시 사이트 설명",
sections: [
// (선택) 서비스 소개 등 정적 페이지 링크 그룹 — 블로그 목록 앞에 출력
{
title: "주요 페이지",
links: [
{
title: "서비스 소개",
url: "https://example.com/services",
note: "제공 서비스 안내",
},
{ title: "상담 문의", url: "https://example.com/contact" },
],
},
],
});
API 조회가 실패해도 항상 200으로 헤더 부분을 반환합니다(빌드 사고 방지).
발행 웹훅의 기본 alsoRevalidate에 /llms.txt가 포함되어 있어, 글을
발행·수정하면 AI 크롤러용 인덱스도 자동으로 갱신됩니다.
에셋 도메인 정합 스캔 (스테이징 잔류 방지)
빌드 산출물의 이미지·스크립트·스타일시트가 스테이징/프리뷰 호스트(예:
*.vercel.app, staging.example.com)를 그대로 참조한 채 배포되면 운영
사이트가 죽은 링크나 깨진 자산을 서빙하게 됩니다. scanAssetHosts는 렌더된
HTML(+ CSS)에서 절대 URL 에셋 호스트를 추출해 허용목록 밖의 호스트, 그리고
허용목록에 있어도 스테이징 패턴이면 무조건 위반으로 보고합니다.
import { scanAssetHosts } from "@roottale/cms-renderer-next/seo-asset-hosts";
const violations = scanAssetHosts(
html, // 렌더된 페이지 HTML — 인라인 <style> 블록도 함께 스캔됨
{ siteHost: "www.example.com", cdnHosts: [".cloudfront.net"] },
[externalCssString], // 선택: 별도로 로드되는 CSS 문자열(@import 1-depth)
);
// violations: { url, host, source, staging? }[] — 0건이면 통과
- 스캔 대상:
<img src>/<img srcset>,<source src>(media)/<source srcset>,<script src>,<video poster>/<video src>,<audio src>,<track src>,<base href>(가장 위험 — 이후 모든 상대 URL이 이 호스트 기준으로 요청됨),<iframe src>,<embed src>/<object data>,<input type="image" src>,<link href>(단rel이 실제로 에셋을 로드하는 값일 때만 —stylesheet/preload/modulepreload/prefetch/preconnect/dns-prefetch/icon류/manifest.canonical/alternate/author/me등은 검사하지 않음),<link imagesrcset>(srcset 문법), 인라인· 외부 CSS의url()/@import/image-set()(-webkit-image-set()포함). - 절대 URL(
https:///http://///host/...)만 판정합니다 — 상대경로·data:/blob:는 통과. 속성값의 HTML 엔티티(&,&#NN;등)는 URL 파싱 전에 디코드하고, URL 안의 백슬래시는 브라우저와 동일하게 슬래시로 정규화합니다.new URL()파싱이 실패하는 절대 URL은 호스트를 추측하지 않고 그 자체로 위반 처리합니다(fail-closed,host: "(unparseable)"). - 한계: HTML 태그는 quote-aware 토크나이저로 스캔하지만 완전한 DOM
파서는 아니라 스크립트 문자열 리터럴 안의 가짜 태그는 걸러내지 못하고, CSS
@import는 1-depth만 보며(중첩@import는 범위 밖), CSS escape 시퀀스 (\3a등)까지는 디코드하지 않습니다. 런타임에 JS로 삽입되는 요청은 배포 후 실제 네트워크 요청을 검사하는 E2E 프로브로 보완하세요.