feat(seo): add SEO/AEO metadata (seo block + page descriptions). 5 page descriptions.#656
Open
dionlow wants to merge 9 commits into
Open
feat(seo): add SEO/AEO metadata (seo block + page descriptions). 5 page descriptions.#656dionlow wants to merge 9 commits into
dionlow wants to merge 9 commits into
Conversation
Improve search and answer-engine (AI) discoverability: - Add an `seo` block to docs.json via generate-docs.ts: og:site_name, indexing "navigable", and organization structured data (publisher entity). - Add answer-first `description` frontmatter to 5 flagship pages (overview, quickstart, read/write/subscribe actions). Descriptions feed the meta description, social preview, search snippet, and the auto-generated llms.txt that AI engines read. First increment of a quick-wins pass; remaining core-page descriptions to follow. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
dionlow
marked this pull request as ready for review
July 21, 2026 23:22
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
dionlow
commented
Jul 21, 2026
dionlow
commented
Jul 21, 2026
dionlow
commented
Jul 21, 2026
Co-authored-by: Dion Low <[email protected]>
Contributor
Author
|
Description adds preview to links: 
|
The `description` frontmatter renders as a visible subtitle under the H1, so it was repeating each page's opening paragraph. Reword descriptions to read cleanly as subtitles (still keyword-rich for SEO/llms.txt) and rewrite the first paragraphs to add complementary detail. Also remove em dashes and fix a "send them" grammar bug on read-actions. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
…lity Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
dionlow
changed the title
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
1 participant
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.
Description
Added descriptions and re-wrote intro paragraphs for 5 core pages. Descriptions double as first paragraph/subtitle under the Title and a summary of the page for LLMs/SEO to capture. They also show as previews in links.
SEO Changes
First increment of an SEO/AEO discoverability pass ("quick wins"). Two self-contained, additive changes:
1.
seoblock indocs.json(added viagenerate-docs.tsso it survives regeneration):og:site_name— social card metadataindexing: "navigable"— index pages in the nav (safe default, matches current behavior)organization— publisher structured data → better Google / AI-engine entity understanding2.
descriptionfrontmatter on 5 flagship pages (overview,quickstart,read-actions,write-actions,subscribe-actions).Why it matters: 326 of 327 pages currently have no
description. In Mintlify,descriptionfeeds the<meta name="description">, the OG/Twitter social preview, the search-result snippet, and the auto-generatedllms.txt/llms-full.txtthat AI answer engines (ChatGPT, Perplexity, Claude, Google AI Overviews) read. Each description here is answer-first, ~150 chars, leading with "Ampersand" + the primary keyword.Deferred (not in this PR)
og:image— omitted to avoid a poor social card from the transparent logo; needs a proper 1200×630 branded image.amp-labs/openapi).Notes for review
src/generate-docs.tsis the source of truth;src/docs.jsonis the regenerated output (committed because Mintlify consumes it). Thedocs.jsondiff is 10 lines, additive only — no navigation churn.indexingto"all".