@core / seo

1.0.0 ▾

1.0.0

인증됨MIT

GitHub

GenPM 사이트 SEO: canonical·hreflang 메타데이터, 분할 사이트맵, robots.txt, llms.txt, 안전한 JSON-LD

코드파일 9개컨텍스트약 639토큰검사 통과

약 639토큰→ src/lib/seo/AGENTS.md→ .cursor/rules/genpm-core-seo.mdc

이것이 AI가 src/lib/seo에서 작업할 때 읽는 내용 그대로입니다. 그 외에는 컨텍스트에 아무것도 추가되지 않습니다.

@core/seo — rules for AI agents

Purpose

Everything search engines and crawling agents read: page metadata with site defaults (title template, description, canonical, hreflang, Open Graph, Twitter, robots), a sitemap index with chunks of 50,000 URLs built from any registered SitemapSource, robots.txt, llms.txt and schema.org JSON-LD builders with script-safe escaping. No tables. OG image generation is out of scope for 1.0.

Map

index.ts — public API: buildMetadata, metaTags, SeoFieldsSchema, jsonLd, jsonLdScript, registerSitemapSource, robotsTxt, llmsTxt.
metadata.ts, jsonld.ts, sitemap.ts, url.ts (SITE_URL helpers).
adapters/hono.ts — seoRoutes(). adapters/next.ts — sitemapIndexRoute, sitemapChunkRoute, robotsRoute.

Integration

Env: SITE_URL (https). In staging set SEO_NOINDEX=1 (noindex everywhere and Disallow: /).
Register sources in src/genpm/seo.ts, imported at startup: registerSitemapSource(contentSitemapSource('pages', ({ slug }) => /${slug})).
Routes: Hono app.route('/', seoRoutes()). Next.js: app/sitemap.xml/route.ts, app/sitemaps/[name]/[file]/route.ts and app/robots.txt/route.ts re-exporting the handlers (see adapters/next.ts), each with export const dynamic = 'force-dynamic' (otherwise next build prerenders them and needs the database and SITE_URL at build time); delete Next's own sitemap.ts/robots.ts if present.
Pages: Next.js export async function generateMetadata() { return buildMetadata({ title, description, path, alternates }) }; other frameworks put metaTags(await buildMetadata(...)) in <head>.
JSON-LD: <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLdScript(jsonLd.product(...)) }} /> (jsonLdScript escapes it, so this is the one safe use of raw HTML).
Add seo: SeoFieldsSchema to collections that need per-entry overrides.
Verify: /sitemap.xml lists chunks, each chunk lists published URLs; page <head> has one canonical.

Conventions

One buildMetadata per page; don't set <title> or description elsewhere.
Canonical paths are the public URL without query strings; pass alternates for every translated page.
noindex previews, internal search results and account pages.

Don't

Don't add ratings, prices or availability to JSON-LD that the page doesn't show or that aren't real.
Don't serialize JSON-LD with plain JSON.stringify inside a script tag.
Don't list drafts or private pages in a sitemap source.

# @core/seo — rules for AI agents

## Purpose
Everything search engines and crawling agents read: page metadata with site defaults (title template, description,
canonical, hreflang, Open Graph, Twitter, robots), a sitemap index with chunks of 50,000 URLs built from any
registered `SitemapSource`, `robots.txt`, `llms.txt` and schema.org JSON-LD builders with script-safe escaping.
No tables. OG image generation is out of scope for 1.0.

## Map
- `index.ts` — public API: `buildMetadata`, `metaTags`, `SeoFieldsSchema`, `jsonLd`, `jsonLdScript`, `registerSitemapSource`, `robotsTxt`, `llmsTxt`.
- `metadata.ts`, `jsonld.ts`, `sitemap.ts`, `url.ts` (`SITE_URL` helpers).
- `adapters/hono.ts` — `seoRoutes()`. `adapters/next.ts` — `sitemapIndexRoute`, `sitemapChunkRoute`, `robotsRoute`.

## Integration
1. Env: `SITE_URL` (https). In staging set `SEO_NOINDEX=1` (noindex everywhere and `Disallow: /`).
2. Register sources in `src/genpm/seo.ts`, imported at startup:
   `registerSitemapSource(contentSitemapSource('pages', ({ slug }) => `/${slug}`))`.
3. Routes: Hono `app.route('/', seoRoutes())`. Next.js: `app/sitemap.xml/route.ts`, `app/sitemaps/[name]/[file]/route.ts`
   and `app/robots.txt/route.ts` re-exporting the handlers (see `adapters/next.ts`), each with `export const dynamic = 'force-dynamic'`
   (otherwise `next build` prerenders them and needs the database and `SITE_URL` at build time); delete Next's own `sitemap.ts`/`robots.ts` if present.
4. Pages: Next.js `export async function generateMetadata() { return buildMetadata({ title, description, path, alternates }) }`;
   other frameworks put `metaTags(await buildMetadata(...))` in `<head>`.
5. JSON-LD: `<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLdScript(jsonLd.product(...)) }} />`
   (`jsonLdScript` escapes it, so this is the one safe use of raw HTML).
6. Add `seo: SeoFieldsSchema` to collections that need per-entry overrides.
7. Verify: `/sitemap.xml` lists chunks, each chunk lists published URLs; page `<head>` has one canonical.

## Conventions
- One `buildMetadata` per page; don't set `<title>` or description elsewhere.
- Canonical paths are the public URL without query strings; pass `alternates` for every translated page.
- `noindex` previews, internal search results and account pages.

## Don't
- Don't add ratings, prices or availability to JSON-LD that the page doesn't show or that aren't real.
- Don't serialize JSON-LD with plain `JSON.stringify` inside a script tag.
- Don't list drafts or private pages in a sitemap source.

.genpmignore 적용 후 주입될 정확한 트리입니다. 고정 대상:

src/lib/seo/LICENSE읽기 전용 · cf4e3c3

MIT License

Copyright (c) 2026 GenPM

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.