# LLM SEO Readiness

> Validates Aptos docs changes for LLM consumption (llms.txt, curated feeds, Markdown exports, HTML→Markdown) and for SEO (metadata, sitemap, robots, structured data). Use when adding or restructuring docs, editing llms routes or curation, changing Head/meta/OG, updating robots.txt or sitemap behavior, or when the user mentions LLMs.txt, AI tool ingestion, crawlers, discoverability, or SEO.

- Skill: `aptos-labs/llm-seo-readiness` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aptos-labs/llm-seo-readiness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aptos-labs/llm-seo-readiness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: aptos-labs (https://skillmd.com/u/aptos-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aptos-labs/llm-seo-readiness

---


# LLM and SEO readiness (Aptos docs)

## LLM / machine-readable

- **Frontmatter**: Every new or renamed doc needs accurate `title` and `description` in English; they surface in `/llms.txt` and `.md` exports. Mirror updates in `src/content/docs/zh/` per agent guidelines (Spanish `es/` is out of scope for agent-maintained docs).
- **Curated lists**: If a page should appear in the LLM index or early in full corpus, update `src/lib/llms-curated-ids.ts` (`LLMS_INDEX_SECTIONS`, `LLMS_SMALL_DOC_IDS`, `FULL_PRIORITY_DOC_IDS` as appropriate). Build fails if an id is missing from English non-draft docs.
- **Index copy**: User-facing explanations live in `src/content/docs/llms-txt.mdx`, `src/content/docs/build/ai.mdx`, and the Chinese `zh/` counterparts—keep URLs and feed names aligned with `src/pages/llms-index.ts`.
- **HTML → Markdown**: Shared logic is `src/lib/llms-html-sanitize.ts`. When minifying for `llms-small.txt`, collapse **spaces/tabs only**—never all `\s` (newlines must survive for fenced code and Markdown structure).
- **Route wiring**: Custom handlers are swapped in via `src/integrations/llms-txt-index.ts`; endpoint implementations live under `src/pages/llms-index.ts`, `src/pages/llms-small.txt.ts`, `src/pages/llms-full.txt.ts`.
- **Robots**: `public/robots.txt` should stay consistent with the sitemap URL (`https://aptos.dev/sitemap.xml`) and, when feeds change, the commented LLMs.txt pointers at the bottom. Keep the `Content-Signal` line intact so AI crawlers see the same preferences the rest of the ecosystem uses. Keep the `Agentmap:` line pointing at `/.well-known/ai-catalog.json`.
- **Agent discovery surface**: `.well-known/api-catalog`, `.well-known/mcp/server-card.json`, `.well-known/agent-skills/index.json`, `.well-known/ai-catalog.json`, the global `Link` header in `vercel.json`, and the Head override's `<link rel="…">` tags must advertise the same URLs. Re-run `pnpm test tests/agent-discovery.test.ts` after any change and see the **Agent discovery & readiness** section of `CLAUDE.md` for the full checklist.

## SEO

- **Per-page metadata**: Starlight frontmatter `title` / `description` feed OG, Twitter, and schema in `src/starlight-overrides/Head.astro`—avoid empty or placeholder descriptions on public pages.
- **Sitemap**: Produced by `@astrojs/sitemap` in `astro.config.mjs` as `sitemap-0.xml` + `sitemap-index.xml`. `src/integrations/sitemap-xml-alias.ts` copies the urlset to `/sitemap.xml` on build, and `vercel.json` rewrites `/sitemap.xml` → `/sitemap-0.xml` as a fallback. Keep `robots.txt` pointing at `/sitemap.xml`.
- **Hreflang / alternates**: Head override builds language alternates from `SUPPORTED_LANGUAGES`—new locales need config updates, not only content folders.
- **Draft / hidden content**: Do not rely on curated LLM ids or public sitemap for content that must stay off production; follow existing draft filtering in the `.md` pipeline and curation tests.

## Verification

After substantive changes:

```bash
pnpm test tests/llms-curated-ids.test.ts tests/llms-html-sanitize.test.ts tests/agent-discovery.test.ts
pnpm lint && pnpm check
```

For full coverage: `pnpm test` and a production `pnpm build` when touching routes or integrations.

## File map

| Area | Primary locations |
|------|-------------------|
| Curation | `src/lib/llms-curated-ids.ts`, `src/lib/llms.ts` |
| llms.txt body | `src/pages/llms-index.ts` |
| Feed endpoints | `src/pages/llms-small.txt.ts`, `src/pages/llms-full.txt.ts` |
| Plugin override | `src/integrations/llms-txt-index.ts` |
| Markdown export / sanitize | `src/lib/llms-html-sanitize.ts`, `src/pages/[...slug].md.ts` |
| User docs | `src/content/docs/llms-txt.mdx`, `build/ai.mdx`, `zh/` |
| SEO head | `src/starlight-overrides/Head.astro` |
| Crawlers / sitemap hint | `public/robots.txt` |
| Agent discovery — well-known | `public/.well-known/api-catalog`, `public/.well-known/mcp/server-card.json`, `public/.well-known/agent-skills/index.json`, `public/.well-known/ai-catalog.json`, `public/.well-known/oauth-protected-resource`, `public/.well-known/openid-configuration`, `public/.well-known/oauth-authorization-server`, `public/auth.md` |
| Agent discovery — Link header | `vercel.json` (global `/(.*)` entry) |
| Markdown negotiation + WebMCP | `src/middlewares/markdown-negotiation.ts`, `src/scripts/webmcp-register.ts`, `src/types/webmcp.d.ts` |
| Agent discovery regression tests | `tests/agent-discovery.test.ts` |