@core / seo

1.0.0 ▾

1.0.0

已验证MIT

GitHub

GenPM 站点 SEO：带 canonical 和 hreflang 的元数据、分片站点地图、robots.txt、llms.txt 和安全的 JSON-LD

代码9 个文件上下文约 639 个 token扫描通过

约 639 个 token→ 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.