UNPKG

@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
--- 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 엔티티(`&amp;`, `&#NN;` 등)는 URL 파싱 전에 디코드하고, URL 안의 백슬래시는 브라우저와 동일하게 슬래시로 정규화합니다. `new URL()` 파싱이 실패하는 절대 URL은 호스트를 추측하지 않고 그 자체로 위반 처리합니다(fail-closed, `host: "(unparseable)"`). - **한계**: HTML 태그는 quote-aware 토크나이저로 스캔하지만 완전한 DOM 파서는 아니라 스크립트 문자열 리터럴 안의 가짜 태그는 걸러내지 못하고, CSS `@import`는 1-depth만 보며(중첩 `@import`는 범위 밖), CSS escape 시퀀스 (`\3a ` 등)까지는 디코드하지 않습니다. 런타임에 JS로 삽입되는 요청은 배포 후 실제 네트워크 요청을 검사하는 E2E 프로브로 보완하세요.