---
description: SEO baseline (robots, sitemap, meta, OG, JSON-LD) and LLM-discoverability baseline (llms.txt, raw .md exposure, AI-bot policy) for the site.
load-when: Updating any SEO surface or LLM-serving artifact.
---
# SEO + LLM serving
Two adjacent surfaces: classic SEO for search engines, and LLM-discoverability for AI agents that read sites. This file covers both.
## SEO surfaces
| Surface | Where | Owner |
| -------------------------- | ----------------------------------------------------------- | ------------------------------------------- |
| `robots.txt` | `static/robots.txt` | Hand-written; references sitemap. |
| Sitemap | Generated → `build/sitemap.xml` | `@docusaurus/plugin-sitemap` (classic preset). |
| Per-page meta | `themeConfig.metadata` in `docusaurus.config.ts` + per-doc frontmatter | Default tags + page-level overrides. |
| OG / Twitter card image | `static/img/og-default.png` | Replace with branded 1200×630 image. |
| JSON-LD `Organization` | `headTags` in `docusaurus.config.ts` | Hand-edited. |
| JSON-LD `Article` | Per-doc — not yet wired | Add when content production starts. |
| 404 page | `src/pages/404.tsx` | Brand-styled. |
| App icons | `static/img/icons/` | `apple-touch-icon`, `icon-192`, `icon-512`. |
| Web manifest | `static/img/icons/site.webmanifest` | Hand-edited. |
## LLM surfaces
| Surface | Where | Notes |
| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------ |
| `llms.txt` | `static/llms.txt` | Follows llmstxt.org schema. |
| Raw `.md` exposure | Generated → `build/educacao/*.md` | `plugins/copy-md/` copies docs sources into `build/`. |
| AI-bot allow directives | `static/robots.txt` | Explicit `Allow:` for GPTBot, ClaudeBot, Google-Extended, PerplexityBot. |
**Per-page meta.** Default site-level tags live in `themeConfig.metadata` (`docusaurus.config.ts`). For a docs entry, override via frontmatter (`title`, `description`, `image`).
**Update OG default image.** Replace `static/img/og-default.png` with a 1200×630 branded card. Reference path is set in `themeConfig.image` — no code change needed.
**Add `Article` JSON-LD per doc.** When a docs entry is substantive enough to warrant rich-result candidacy, add a `` block via Docusaurus's per-doc head injection (or via a swizzle of `DocItem`).
**Update `llms.txt` after every new entry.** Add the new entry under the matching `## Section` block with a link to the `.md` URL. The `copy-md` plugin auto-publishes the raw `.md` — no additional step needed.
**Change the AI-bot policy.** Edit `static/robots.txt` directly. Allow / Disallow per User-agent. Re-deploy. No config change needed — it is a static file.
- Generating sitemap manually — the plugin handles it; manual edits get overwritten.
- Hardcoding OG image per page when one default suffices — over-engineering for a foundation site.
- Forgetting to update `llms.txt` after a new docs entry — site stays browser-readable but the LLM index drifts.
- Removing the `copy-md` plugin without updating `llms.txt` URLs — `.md` URLs would 404.