@roottale/cms-mcp
Version:
RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.
1,237 lines (1,027 loc) • 69.8 kB
Markdown
---
title: SEO (RSS·사이트맵·JSON-LD)
description: RSS 피드, 사이트맵, JSON-LD 스키마, fleet 프로브 라우트
---
# SEO — RSS·사이트맵·JSON-LD
`@roottale/cms-renderer-next/routes`의 팩토리로 RSS·사이트맵을 한 줄에
구성하고, `@roottale/cms-client/server`의 헬퍼로 JSON-LD를 생성합니다.
고정 페이지의 검색·공유 메타데이터는 아래 [공통 메타데이터](#공통-메타데이터)를 참고하세요.
## RSS 피드
```ts
// 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 설치만으로 편집을 열지는 않으며 실제 배포 계약·연동 증거가 필요합니다.
```ts
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는 아닙니다.
```ts
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 페이지 예제](../examples/nextjs/lib/page-metadata.ts)는 정책을
그대로 받는 선택 인자를 제공합니다.
### 동적 콘텐츠의 공개·색인 정책
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`은 정책 의존 값이 포함될 수 있는
불투명 문자열이므로 그대로 전달하며 숫자로 변환하거나 증가시키지 않습니다.
```ts
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`인 경우로 한정한다면, 다음 조건들을 **같은 전체 정책**의
검수·출연자·출처 검사에 연결합니다. 예외일 때만 일부 검사를 생략하고, 출처 필수와
강제 검색 제외는 유지합니다. 이 조건 선언만으로 글을 공개하지는 않습니다.
```ts
// 실행 예제 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`에는 위 모델 정보를 돌려주는
사이트 함수를 전달합니다.
```ts
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이며, 여러 화면에서 재사용할 때는 위처럼 두 평가를 분리합니다.
캐시 연결은 [발행 웹훅 문서](revalidation-webhooks.md)의 공개 정책 절을 따릅니다.
### 관리 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
한도에도 안전합니다. 발행 글·카테고리는 자동 포함됩니다.
```ts
// 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`로 둡니다.
```tsx
// 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`:
```tsx
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)` 가 짝입니다.
```tsx
// 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)](./collections.md)
에 정리되어 있습니다. 여기 sitemap/feed 예시도 `collections`를 넘기면 섹션별로 파생됩니다.
## robots.txt
크롤링 제어의 기본. sitemap 위치를 알려주고, 크롤링이 무의미한 경로만
차단합니다. **CSS/JS/이미지 경로를 차단하지 마세요** — 구글이 페이지를
렌더링하지 못해 평가가 깨집니다. 색인 제외가 목적이면 robots.txt 차단이
아니라 페이지의 noindex 를 쓰세요 (외부 링크가 있으면 차단해도 색인될 수
있습니다).
```ts
// 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"`가 함께 들어갑니다.
```ts
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):
```tsx
<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 브레드크럼과 구조 일치 권장):
```tsx
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` 까지 다시 채웁니다.
```tsx
// 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
미설정), 이 헬퍼로 표준화합니다.
```tsx
// 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.ogImage` override → 없으면 글 값 fallback
- canonical: `seo.canonical` override → 없으면 `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).
```tsx
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 을 갖게 됩니다.
```tsx
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`)이 자동으로 붙습니다:
```tsx
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]` 페이지 등)는 `pathFor` override 필수 —
`buildHreflangLanguages(translations, siteUrl, { defaultLocale, pathFor })`
를 직접 호출하면 OG `type:"article"` 없이 plain `alternates` 만 조립할 수
있습니다.
- `translations` 가 없거나(구 서버) 자기 자신 1건뿐(번역 없음)이면 `languages`
자체가 생략됩니다 — 단일 언어 사이트는 기존 canonical-only 동작 그대로.
## slug 변경 시 301 리다이렉트
글 slug를 바꿔도 옛 URL이 깨지지 않습니다. API가 slug history로 글을 찾아
**현재 slug로 응답**하므로, 페이지에서 요청 slug와 비교해 301을 보내세요:
```tsx
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 부분셋을 런타임에 받아 렌더합니다.
```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; // { 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에서만 사용합니다:
```tsx
// 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}`) |
```tsx
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 구조 — 확장 옵션(전부 선택)**:
```tsx
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회 렌더하면 충분합니다:
```tsx
// 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` / `areaServed`
- `alternateName`: 띄어쓰기 변형처럼 같은 사업장을 다르게 부르는 이름
- `hasOfferCatalog`: 어드민 "취급 업무" 목록 — "무엇을 하는 곳인가"를 명시하는
신호입니다. 명함·간판에 적힌 업무를 그대로 옮기면 됩니다.
- `hasMap`: 네이버플레이스 주소(없으면 카카오맵 주소)
- `sameAs`: 어드민에 입력한 네이버플레이스·구글 비즈니스 프로필·카카오 채널
등의 URL — 검색엔진이 동일 사업장임을 연결합니다. 지도 딥링크(카카오맵)는
프로필 페이지가 아니므로 `hasMap` 으로만 나가고 여기엔 포함되지 않습니다.
`faxNumber`는 고객이 사업장 정보에서 바꿀 수 있으며, 스타터와
`localBusinessSchema`가 자동으로 JSON-LD에 반영합니다. `priceRange`는 업종별 의미가
달라 공통 관리자·스타터가 관리하지 않습니다. 필요하면 사이트 프로젝트가
`localBusinessSchema` 입력에 명시적으로 추가합니다.
네이버플레이스([new.smartplace.naver.com](https://new.smartplace.naver.com))와
구글 비즈니스 프로필([business.google.com](https://business.google.com)) 등록
자체는 공개 API가 없어 사장님이 직접 해야 하며, 어드민 화면에 등록 안내와
프로필 URL 입력란이 있습니다.
## Fleet 프로브 (운영 가시성)
ROOT-ADMIN 직원용 ‘전 사이트’ 화면이 배포 버전과 보안패치 상태를 확인하는
well-known 라우트입니다. CMS 정보는 기존 SDK를 사용하고 실행 버전을 덧붙입니다.
```ts
// 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](https://llmstxt.org) 마크다운 인덱스로 사이트 구조와 콘텐츠를
빠르게 파악합니다. 발행 글 목록(최대 100개)을 제목·요약과 함께 자동
포함하므로, AI가 관련 질문에 답할 때 내 사이트의 글이 출처로 인용될
가능성을 높입니다(AEO/GEO).
```ts
// 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 에셋 호스트를 추출해 허용목록 밖의 호스트, 그리고
허용목록에 있어도 스테이징 패턴이면 무조건 위반으로 보고합니다.
```ts
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 프로브로 보완하세요.