@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/adapters/hono.ts읽기 전용 · cf4e3c3

// Adaptador Hono: `app.route('/', seoRoutes())` → /sitemap.xml, /sitemaps/:name/:n.xml y /robots.txt.
import { Hono } from 'hono';
import { robotsTxt, sitemapChunkXml, sitemapIndexXml } from '../index.ts';

const XML = { 'content-type': 'application/xml; charset=utf-8', 'cache-control': 'public, max-age=3600' };

export function seoRoutes(opts: { disallow?: string[] } = {}) {
  return new Hono()
    .get('/sitemap.xml', async (c) => c.body(await sitemapIndexXml(), 200, XML))
    .get('/sitemaps/:name/:file', async (c) => {
      const m = /^(\d{1,4})\.xml$/.exec(c.req.param('file'));
      const body = m ? await sitemapChunkXml(c.req.param('name'), Number(m[1])) : null;
      return body ? c.body(body, 200, XML) : c.notFound();
    })
    .get('/robots.txt', (c) => c.text(robotsTxt(opts)));
}