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) <noreply@anthropic.com>
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 <dionlow17@gmail.com>
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) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…lity Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
laurenzlong
approved these changes
Jul 23, 2026
| --- | ||
|
|
||
| [Ampersand](https://www.withampersand.com/) is a declarative platform for SaaS builders who are creating product integrations. It allows you to: | ||
| A single [Ampersand](https://www.withampersand.com/) integration gives the following capabilities: |
Contributor
There was a problem hiding this comment.
Suggested change
| A single [Ampersand](https://www.withampersand.com/) integration gives the following capabilities: | |
| [Ampersand](https://www.withampersand.com/) is a platform for building deep integration with capabilities like: |
| --- | ||
|
|
||
| A read action reads data from your customer's SaaS and send them to Destinations that you define. | ||
| Data read from your customer's SaaS is delivered to the [Destinations](/destinations) you define. |
Contributor
There was a problem hiding this comment.
Suggested change
| Data read from your customer's SaaS is delivered to the [Destinations](/destinations) you define. | |
| Read actions fetch data from your customer's SaaS and deliver them to the [Destinations](/destinations) you define. |
| --- | ||
|
|
||
| A write action writes data to your customer's SaaS whenever you make an API request to us. This page focuses on writing data to existing fields. If you are looking to create new custom fields prior to writing data, please see [Create or update custom fields](/manage-customer-schemas#create-or-update-custom-fields). | ||
| Write actions run on demand: Ampersand writes to your customer's SaaS whenever you make an API request. This page focuses on writing to existing fields. To create custom fields first, see [Create or update custom fields](/manage-customer-schemas#create-or-update-custom-fields). |
Contributor
There was a problem hiding this comment.
Suggested change
| Write actions run on demand: Ampersand writes to your customer's SaaS whenever you make an API request. This page focuses on writing to existing fields. To create custom fields first, see [Create or update custom fields](/manage-customer-schemas#create-or-update-custom-fields). | |
| Write actions run on demand: Ampersand writes to your customer's SaaS whenever you make an API request. This page focuses on writing to existing fields. To create custom fields, see [Create or update custom fields](/manage-customer-schemas#create-or-update-custom-fields). |
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
2 participants
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".