seo-graph

Agent-ready SEO for JavaScript: schema.org JSON-LD graph builders, a deterministic agent-markdown pipeline, and HTTP content negotiation — with an Astro integration.

Sites are read by two audiences now. This toolkit serves both from one place: typed schema.org @graph output for structured-data consumers, and byte-stable Markdown representations of every page (with llms.txt, a route manifest, IndexNow, and Accept: text/markdown negotiation) for AI agents.

Package	Purpose
@iannuttall/seo-graph-core	Pure, runtime-agnostic core. Schema piece builders and graph assembler (typed by schema-dts), the built-HTML → Markdown renderer with a strict content-selection contract, MDX cleaning, route mapping, manifests, validated llms.txt v2 output, git-based lastmod, and IndexNow hashing.
@iannuttall/seo-graph-astro	Astro layer. agentMarkdown() build integration, opt-in generic content negotiation, Markdown response and collection helpers, schema endpoints + schema map, IndexNow key route, RFC 9727 api-catalog, Zod content helpers, and a static-asset Cloudflare handler (./cloudflare).

Why not convert HTML at the edge?

Managed edge HTML→Markdown conversion has no exclusion contract: decorative markup, aria-hidden card internals, and form labels leak into what agents read, and you cannot fix it from your codebase. This pipeline runs at build time against markup you own — decorative elements are stripped by contract (data-agent-markdown="exclude", aria-hidden, forms, nav), collection pages serve their exact source Markdown, output is deterministic to the byte, and violations can fail the build instead of shipping.

Documentation

See AGENTS.md for the full reference — schema builder signatures, site-type recipes, the markdown content-selection contract, and every integration surface. It's written for both humans and AI coding agents (CLAUDE.md symlinks to it).

Quick start (Astro)

pnpm add @iannuttall/seo-graph-astro @iannuttall/seo-graph-core

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { agentMarkdown } from '@iannuttall/seo-graph-astro';

export default defineConfig({
    site: 'https://example.com',
    integrations: [
        agentMarkdown({
            llmsTxt: {
                title: 'Example',
                summary: 'Useful pages from Example.',
            },
            // Optional. Defaults to false, so static sites keep no runtime cost.
            // runtimeMiddleware: true,
            // The build warns about old /page.md URLs that move to
            // /page/index.md. Disable this after you add redirects.
            // routeMigrationWarnings: false,
        }),
    ],
});

Develop

pnpm install
pnpm build
pnpm typecheck
pnpm test

Releases publish from CI via npm trusted publishing on v* tags.

License

MIT © Ian Nuttall. Portions of the schema layer derive from jdevalk/seo-graph by Joost de Valk (MIT) — see NOTICE.