From 0c37856f186f21c5126622806dc2060ec91b412c Mon Sep 17 00:00:00 2001 From: Dion Low Date: Tue, 21 Jul 2026 16:20:55 -0700 Subject: [PATCH 1/9] feat(seo): add SEO/AEO metadata (seo block + page descriptions) 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) --- src/docs.json | 10 ++++++++++ src/generate-docs.ts | 19 +++++++++++++++++++ src/overview.mdx | 1 + src/quickstart.mdx | 1 + src/read-actions.mdx | 1 + src/subscribe-actions.mdx | 1 + src/write-actions.mdx | 1 + 7 files changed, 34 insertions(+) diff --git a/src/docs.json b/src/docs.json index 5ff9a150..b6fd7af9 100644 --- a/src/docs.json +++ b/src/docs.json @@ -14,6 +14,16 @@ "view" ] }, + "seo": { + "metatags": { + "og:site_name": "Ampersand Docs" + }, + "indexing": "navigable", + "organization": { + "name": "Ampersand", + "url": "https://withampersand.com" + } + }, "navigation": { "tabs": [ { diff --git a/src/generate-docs.ts b/src/generate-docs.ts index f4be820d..9b9d5ec5 100644 --- a/src/generate-docs.ts +++ b/src/generate-docs.ts @@ -28,6 +28,15 @@ export interface DocsConfig { contextual?: { options: Array; }; + seo?: { + metatags?: Record; + indexing?: string; + organization?: { + name?: string; + url?: string; + logo?: string; + }; + }; navigation: { tabs: Array<{ tab: string; @@ -115,6 +124,16 @@ export function generateDocsConfig(mintConfig: any): DocsConfig { contextual: { options: ['copy', 'view'] }, + seo: { + metatags: { + 'og:site_name': 'Ampersand Docs' + }, + indexing: 'navigable', + organization: { + name: 'Ampersand', + url: 'https://withampersand.com' + } + }, navigation: { tabs: [ { diff --git a/src/overview.mdx b/src/overview.mdx index a79f6b67..30c57a0e 100644 --- a/src/overview.mdx +++ b/src/overview.mdx @@ -1,5 +1,6 @@ --- title: "Overview" +description: "Ampersand is a declarative platform for SaaS builders to read, write, and subscribe to data in your customers' SaaS apps without building per-provider integrations." --- [Ampersand](https://www.withampersand.com/) is a declarative platform for SaaS builders who are creating product integrations. It allows you to: diff --git a/src/quickstart.mdx b/src/quickstart.mdx index 489432da..5ff1642c 100644 --- a/src/quickstart.mdx +++ b/src/quickstart.mdx @@ -1,5 +1,6 @@ --- title: "Quickstart" +description: "Build your first SaaS integration with Ampersand in minutes — create a project, define an amp.yaml manifest, and read and write customer data through a unified API." --- For this Quickstart, we are going to build integrations for a cool new app called MailMonkey - an AI-powered email campaign manager that integrates with Salesforce. You can see the final `amp.yaml` file on [Github](https://github.com/amp-labs/samples/blob/main/quickstart/amp.yaml). diff --git a/src/read-actions.mdx b/src/read-actions.mdx index 41574d84..150847de 100644 --- a/src/read-actions.mdx +++ b/src/read-actions.mdx @@ -1,5 +1,6 @@ --- title: "Read actions" +description: "Sync data from any SaaS API into your product with Ampersand read actions — scheduled or on-demand reads, historical backfill, incremental reads, and filters." --- A read action reads data from your customer's SaaS and send them to Destinations that you define. diff --git a/src/subscribe-actions.mdx b/src/subscribe-actions.mdx index 73d42b08..fefb2f32 100644 --- a/src/subscribe-actions.mdx +++ b/src/subscribe-actions.mdx @@ -1,5 +1,6 @@ --- title: "Subscribe actions" +description: "Receive near-instant webhooks when records are created, updated, or deleted in your customers' SaaS apps with Ampersand subscribe actions." --- With subscribe actions, you'll receive near-instant webhooks as events occur in your customers' SaaS applications. This enables your application to quickly react to events such as record creation, deletion, and field updates. diff --git a/src/write-actions.mdx b/src/write-actions.mdx index abda51f6..4739cd9d 100644 --- a/src/write-actions.mdx +++ b/src/write-actions.mdx @@ -1,5 +1,6 @@ --- title: "Write actions" +description: "Write data to your customers' SaaS apps with Ampersand write actions — create and update standard and custom objects, including bulk writes, through one API." --- 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). From d3dea682508c9986e6201a96cf1cd2d6d5cefb00 Mon Sep 17 00:00:00 2001 From: Dion Low Date: Tue, 21 Jul 2026 16:30:00 -0700 Subject: [PATCH 2/9] Apply suggestions from code review Co-authored-by: Dion Low --- src/quickstart.mdx | 2 +- src/read-actions.mdx | 2 +- src/write-actions.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/quickstart.mdx b/src/quickstart.mdx index 5ff1642c..e062a5dd 100644 --- a/src/quickstart.mdx +++ b/src/quickstart.mdx @@ -1,6 +1,6 @@ --- title: "Quickstart" -description: "Build your first SaaS integration with Ampersand in minutes — create a project, define an amp.yaml manifest, and read and write customer data through a unified API." +description: "Build your first SaaS integration with Ampersand in minutes: create a project, define an amp.yaml manifest, and read and write customer data through a unified API." --- For this Quickstart, we are going to build integrations for a cool new app called MailMonkey - an AI-powered email campaign manager that integrates with Salesforce. You can see the final `amp.yaml` file on [Github](https://github.com/amp-labs/samples/blob/main/quickstart/amp.yaml). diff --git a/src/read-actions.mdx b/src/read-actions.mdx index 150847de..16353206 100644 --- a/src/read-actions.mdx +++ b/src/read-actions.mdx @@ -1,6 +1,6 @@ --- title: "Read actions" -description: "Sync data from any SaaS API into your product with Ampersand read actions — scheduled or on-demand reads, historical backfill, incremental reads, and filters." +description: "Read data from any SaaS API into your product with Ampersand read actions: scheduled or on-demand reads, historical backfill, incremental reads, and filters." --- A read action reads data from your customer's SaaS and send them to Destinations that you define. diff --git a/src/write-actions.mdx b/src/write-actions.mdx index 4739cd9d..e129f753 100644 --- a/src/write-actions.mdx +++ b/src/write-actions.mdx @@ -1,6 +1,6 @@ --- title: "Write actions" -description: "Write data to your customers' SaaS apps with Ampersand write actions — create and update standard and custom objects, including bulk writes, through one API." +description: "Write data to your customers' SaaS apps with Ampersand write actions: create and update standard and custom objects, including bulk writes, through one API." --- 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). From 94a185df4b3cac8c206569471f773b382cdbb025 Mon Sep 17 00:00:00 2001 From: Dion Low Date: Tue, 21 Jul 2026 16:50:54 -0700 Subject: [PATCH 3/9] refactor(seo): de-dupe description subtitle vs. first paragraph 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) --- src/overview.mdx | 10 ++-------- src/quickstart.mdx | 2 +- src/read-actions.mdx | 4 ++-- src/subscribe-actions.mdx | 4 ++-- src/write-actions.mdx | 4 ++-- 5 files changed, 9 insertions(+), 15 deletions(-) diff --git a/src/overview.mdx b/src/overview.mdx index 30c57a0e..820c026c 100644 --- a/src/overview.mdx +++ b/src/overview.mdx @@ -1,15 +1,9 @@ --- title: "Overview" -description: "Ampersand is a declarative platform for SaaS builders to read, write, and subscribe to data in your customers' SaaS apps without building per-provider integrations." +description: "Ampersand is a declarative platform for reading, writing, and subscribing to data in your customers' SaaS apps. Define your integrations once and skip the per-provider code." --- -[Ampersand](https://www.withampersand.com/) is a declarative platform for SaaS builders who are creating product integrations. It allows you to: - -* Read data from your customer's SaaS -* Write data to your customer's SaaS -* Subscribe to events (creates, deletes, and field changes) in your customer's SaaS. - -Here's an overview of the Ampersand platform: +[Ampersand](https://www.withampersand.com/) manages the full lifecycle of your product integrations, including auth, scheduled and on-demand syncs, retries, and error handling, so you can focus on your product. Here's an overview of the platform: ![The Ampersand platform](/images/overview.png) diff --git a/src/quickstart.mdx b/src/quickstart.mdx index e062a5dd..8d56af8c 100644 --- a/src/quickstart.mdx +++ b/src/quickstart.mdx @@ -1,6 +1,6 @@ --- title: "Quickstart" -description: "Build your first SaaS integration with Ampersand in minutes: create a project, define an amp.yaml manifest, and read and write customer data through a unified API." +description: "Build your first SaaS integration with Ampersand in minutes. Create a project, define an amp.yaml manifest, and read and write customer data through a unified API." --- For this Quickstart, we are going to build integrations for a cool new app called MailMonkey - an AI-powered email campaign manager that integrates with Salesforce. You can see the final `amp.yaml` file on [Github](https://github.com/amp-labs/samples/blob/main/quickstart/amp.yaml). diff --git a/src/read-actions.mdx b/src/read-actions.mdx index 16353206..c9c4c3eb 100644 --- a/src/read-actions.mdx +++ b/src/read-actions.mdx @@ -1,9 +1,9 @@ --- title: "Read actions" -description: "Read data from any SaaS API into your product with Ampersand read actions: scheduled or on-demand reads, historical backfill, incremental reads, and filters." +description: "Read data from your customers' SaaS on a schedule or on demand, with backfill, incremental reads, and filters." --- -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. ## Define reads diff --git a/src/subscribe-actions.mdx b/src/subscribe-actions.mdx index fefb2f32..33db3b3a 100644 --- a/src/subscribe-actions.mdx +++ b/src/subscribe-actions.mdx @@ -1,9 +1,9 @@ --- title: "Subscribe actions" -description: "Receive near-instant webhooks when records are created, updated, or deleted in your customers' SaaS apps with Ampersand subscribe actions." +description: "Get near-instant webhooks when records are created, updated, or deleted in your customers' SaaS apps." --- -With subscribe actions, you'll receive near-instant webhooks as events occur in your customers' SaaS applications. This enables your application to quickly react to events such as record creation, deletion, and field updates. +Subscribe actions let your app react in real time: instead of polling on a schedule, Ampersand pushes an event to your destination as soon as it happens in your customer's SaaS. Please note that: diff --git a/src/write-actions.mdx b/src/write-actions.mdx index e129f753..f2a6b2b0 100644 --- a/src/write-actions.mdx +++ b/src/write-actions.mdx @@ -1,9 +1,9 @@ --- title: "Write actions" -description: "Write data to your customers' SaaS apps with Ampersand write actions: create and update standard and custom objects, including bulk writes, through one API." +description: "Write data to your customers' SaaS on demand. Create and update standard and custom objects, including bulk writes." --- -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). ## Defining writes From f385b714c2fdca3fa4b0209b38ed9eeabebc0aa1 Mon Sep 17 00:00:00 2001 From: Dion Low Date: Tue, 21 Jul 2026 16:56:31 -0700 Subject: [PATCH 4/9] docs(subscribe): link destination to /destinations Co-Authored-By: Claude Opus 4.8 (1M context) --- src/subscribe-actions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/subscribe-actions.mdx b/src/subscribe-actions.mdx index 33db3b3a..67bc93a1 100644 --- a/src/subscribe-actions.mdx +++ b/src/subscribe-actions.mdx @@ -3,7 +3,7 @@ title: "Subscribe actions" description: "Get near-instant webhooks when records are created, updated, or deleted in your customers' SaaS apps." --- -Subscribe actions let your app react in real time: instead of polling on a schedule, Ampersand pushes an event to your destination as soon as it happens in your customer's SaaS. +Subscribe actions let your app react in real time: instead of polling on a schedule, Ampersand pushes an event to your [destination](/destinations) as soon as it happens in your customer's SaaS. Please note that: From 0d9793e72f6b7371b078db950ff0562fe81a2ec7 Mon Sep 17 00:00:00 2001 From: Dion Low Date: Tue, 21 Jul 2026 16:59:30 -0700 Subject: [PATCH 5/9] docs(overview): restore read/write/subscribe bullet list for scannability Co-Authored-By: Claude Opus 4.8 (1M context) --- src/overview.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/overview.mdx b/src/overview.mdx index 820c026c..05c8d35c 100644 --- a/src/overview.mdx +++ b/src/overview.mdx @@ -3,7 +3,13 @@ title: "Overview" description: "Ampersand is a declarative platform for reading, writing, and subscribing to data in your customers' SaaS apps. Define your integrations once and skip the per-provider code." --- -[Ampersand](https://www.withampersand.com/) manages the full lifecycle of your product integrations, including auth, scheduled and on-demand syncs, retries, and error handling, so you can focus on your product. Here's an overview of the platform: +[Ampersand](https://www.withampersand.com/) is a declarative platform for building product integrations without per-provider code. With a single integration, you can: + +* Read data from your customer's SaaS +* Write data to your customer's SaaS +* Subscribe to events (creates, deletes, and field changes) in your customer's SaaS + +Ampersand manages the full lifecycle for you, including auth, scheduled and on-demand syncs, retries, and error handling, so you can focus on your product. Here's an overview of the platform: ![The Ampersand platform](/images/overview.png) From 2b77e51ff876fe59787dfeae8ba775fc5f8e0fa2 Mon Sep 17 00:00:00 2001 From: Dion Low Date: Tue, 21 Jul 2026 17:00:37 -0700 Subject: [PATCH 6/9] docs(overview): drop duplicated platform sentence, lead with bullets Co-Authored-By: Claude Opus 4.8 (1M context) --- src/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/overview.mdx b/src/overview.mdx index 05c8d35c..c0539860 100644 --- a/src/overview.mdx +++ b/src/overview.mdx @@ -3,7 +3,7 @@ title: "Overview" description: "Ampersand is a declarative platform for reading, writing, and subscribing to data in your customers' SaaS apps. Define your integrations once and skip the per-provider code." --- -[Ampersand](https://www.withampersand.com/) is a declarative platform for building product integrations without per-provider code. With a single integration, you can: +With a single [Ampersand](https://www.withampersand.com/) integration, you can: * Read data from your customer's SaaS * Write data to your customer's SaaS From d376b1abb81ca4c118d654731ccd1375d6f6d6f3 Mon Sep 17 00:00:00 2001 From: Dion Low Date: Tue, 21 Jul 2026 17:02:06 -0700 Subject: [PATCH 7/9] docs(overview): convert capabilities bullets to a table Co-Authored-By: Claude Opus 4.8 (1M context) --- src/overview.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/overview.mdx b/src/overview.mdx index c0539860..2606bb7c 100644 --- a/src/overview.mdx +++ b/src/overview.mdx @@ -3,11 +3,13 @@ title: "Overview" description: "Ampersand is a declarative platform for reading, writing, and subscribing to data in your customers' SaaS apps. Define your integrations once and skip the per-provider code." --- -With a single [Ampersand](https://www.withampersand.com/) integration, you can: +A single [Ampersand](https://www.withampersand.com/) integration gives you three capabilities: -* Read data from your customer's SaaS -* Write data to your customer's SaaS -* Subscribe to events (creates, deletes, and field changes) in your customer's SaaS +| Action | What it does | +| --- | --- | +| **Read** | Pull data from your customer's SaaS | +| **Write** | Push data to your customer's SaaS | +| **Subscribe** | Receive events (creates, deletes, and field changes) from your customer's SaaS | Ampersand manages the full lifecycle for you, including auth, scheduled and on-demand syncs, retries, and error handling, so you can focus on your product. Here's an overview of the platform: From af6bc107ce7c3a0166becccbb4fac9e0d7e0b136 Mon Sep 17 00:00:00 2001 From: Dion Low Date: Tue, 21 Jul 2026 17:04:17 -0700 Subject: [PATCH 8/9] docs(overview): reword capabilities lead-in Co-Authored-By: Claude Opus 4.8 (1M context) --- src/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/overview.mdx b/src/overview.mdx index 2606bb7c..9a9d2f1b 100644 --- a/src/overview.mdx +++ b/src/overview.mdx @@ -3,7 +3,7 @@ title: "Overview" description: "Ampersand is a declarative platform for reading, writing, and subscribing to data in your customers' SaaS apps. Define your integrations once and skip the per-provider code." --- -A single [Ampersand](https://www.withampersand.com/) integration gives you three capabilities: +A single [Ampersand](https://www.withampersand.com/) integration gives the following capabilities: | Action | What it does | | --- | --- | From fea34538bfec5eb00263f6a8982065ced9d262d9 Mon Sep 17 00:00:00 2001 From: Dion Low Date: Tue, 21 Jul 2026 17:08:31 -0700 Subject: [PATCH 9/9] docs(subscribe): add sentence on reacting to record events Co-Authored-By: Claude Opus 4.8 (1M context) --- src/subscribe-actions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/subscribe-actions.mdx b/src/subscribe-actions.mdx index 67bc93a1..d14c3f80 100644 --- a/src/subscribe-actions.mdx +++ b/src/subscribe-actions.mdx @@ -3,7 +3,7 @@ title: "Subscribe actions" description: "Get near-instant webhooks when records are created, updated, or deleted in your customers' SaaS apps." --- -Subscribe actions let your app react in real time: instead of polling on a schedule, Ampersand pushes an event to your [destination](/destinations) as soon as it happens in your customer's SaaS. +Subscribe actions let your app react in real time: instead of polling on a schedule, Ampersand pushes an event to your [destination](/destinations) as soon as it happens in your customer's SaaS. These capabilities enable your application to quickly react to events such as record creation, deletion, and field updates. Please note that: