feat(docs): SEO and AEO optimization#78
Merged
Merged
Conversation
Add discovery and structured-data assets so the TRACE docs are indexed by search engines and cited by AI answer engines: - llms.txt and llms-full.txt via the mkdocs-llmstxt plugin - robots.txt at the site root that welcomes AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, and others) and points to the sitemap - Organization, WebSite, and SoftwareApplication JSON-LD plus OpenGraph and Twitter card meta on every page via a theme override (overrides/main.html) - FAQPage JSON-LD and an answer-first FAQ, a TL;DR block, and per-page meta descriptions on non-normative pages (home, quickstart, trust levels) The docs CI assemble step now also copies robots.txt to the build root. No normative spec text was changed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a 1200x630 Open Graph card served at /docs/assets/og.png and wires og:image plus twitter:image (summary_large_image). Corrects the publisher name in JSON-LD from AgentTrust to AgenTrust. No normative spec text changed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What and why
Makes the TRACE docs discoverable by both search engines and AI answer engines (LLMs). Today the site has no llms.txt, no structured data, and no robots.txt, so it is under-picked-up by Google AI Overviews, Perplexity, ChatGPT, and Claude. This PR is additive scaffolding plus answer-first framing on non-normative pages.
Changes
AEO (LLM / answer-engine pickup)
llms.txtandllms-full.txtgenerated at the site root via themkdocs-llmstxtplugin, with a curated summary and sectioned links (Getting started, Specification, Integration, Platforms).robots.txtat the site root that welcomes major AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, anthropic-ai, PerplexityBot, Google-Extended, CCBot) and points to the sitemap.FAQPageJSON-LD plus a visible answer-first FAQ on the home page.SEO
Organization,WebSite, andSoftwareApplicationJSON-LD plus OpenGraph and Twitter card meta on every page, injected through a new theme override (overrides/main.html). Canonical is left to Material (it already emits it becausesite_urlis set).descriptionfront matter and a TL;DR block on the home, quickstart, and trust-levels pages.sitemap.xmlcontinues to auto-generate (28 URLs).Build
mkdocs-llmstxttorequirements-docs.txt.robots.txtinto the build root (the site usesdocs_dir: .with a.docs_buildassemble), and the workflow rebuilds onoverrides/**androbots.txtchanges.Verification checklist (built locally via the CI-replicated assemble)
mkdocs buildsucceeds (non-strict; see caveat).site/llms.txt(1.5 KB) andsite/llms-full.txt(93 KB) present at root.site/robots.txtserved at root with sitemap reference.site/sitemap.xmlpresent, 28 URLs incl./.[Organization, WebSite, SoftwareApplication]andFAQPage.Caveats / follow-ups
mkdocs build --strictstill aborts, but only on 7 pre-existing warnings unrelated to this PR (broken links in README.md and GOVERNANCE.md, pages not in nav,docs/tutorials/agt-adapter.mdlinks). Worth a separate cleanup PR to enable strict.og:imageyet: the repo only hasicon.svg(no raster social card). Adding a 1200x630 PNG is a good follow-up. The Material auto social-card plugin was intentionally not enabled because the docs CI lacks the cairo/pango system libraries and would break the build./docs/). The true site root/isREADME.md; it still gets the site-wide JSON-LD and OG meta via the override. Aligning the site root with the docs home is a separate structural decision.Do NOT merge without a Maintain+ review (the maintainer-approval gate applies).