Skip to content

docs: redesign home page #730

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
buildstuff-2026 wants to merge 1 commit into from
Draft

docs: redesign home page #730

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 181 additions & 0 deletions src/home.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
/* Docs home page (src/overview.mdx).
Only the hero and the provider browser are custom. Every other section on
that page uses native Mintlify components, so it inherits the docs' own
colors, type, and spacing. Everything here is scoped under .amp-home (or to
the home page's own path), so nothing leaks into the rest of the site. */

/* The hero replaces Mintlify's page title on this page only. */
html[data-current-path="/"] #header,
html[data-current-path="/overview"] #header { display: none; }

.amp-home {
container-type: inline-size;

/* Mintlify's own gray ramp plus this project's brand accent, so the custom
sections sit next to the generated ones without a visible seam. */
--amp-bg: #ffffff;
--amp-fg: #19171c; /* gray-900 */
--amp-fg-2: #403f44; /* gray-700, docs body text */
--amp-muted: #525055; /* gray-600 */
--amp-muted-2: #727075; /* gray-500 */
--amp-faint: #a09fa4; /* gray-400 */
--amp-comment: #a09fa4;
--amp-accent: #6122E7;
--amp-accent-hover: #8850FF;
--amp-heading-accent: #4F1EB8;
--amp-green: #0d8f6c;
--amp-surface: #ffffff;
--amp-surface-2: #f5f3f8; /* gray-50 */
--amp-border: rgba(9, 9, 11, 0.1); /* same hairline as native cards */
--amp-border-2: #f0eef3; /* gray-100 */
--amp-border-input: #e0dfe4; /* gray-200 */
--amp-border-hover: #d0ced3; /* gray-300 */

/* Mintlify loads its fonts via next/font and exposes them as variables;
consuming those keeps this page on the docs' typeface automatically. */
--amp-sans: var(--font-family-body-custom, var(--font-inter, ui-sans-serif)), -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
--amp-mono: var(--font-family-mono-custom, var(--font-jetbrains-mono, ui-monospace)), "SF Mono", SFMono-Regular, Menlo, Consolas, monospace;

font-family: var(--amp-sans);
color: var(--amp-fg);
letter-spacing: -0.0125rem; /* docs prose tracking */
line-height: 1.5;
}

html.dark .amp-home {
--amp-bg: #0f1117; /* Mintlify --background-dark */
--amp-fg: #e0dfe4; /* gray-200 */
--amp-fg-2: #d0ced3;
--amp-muted: #a09fa4;
--amp-muted-2: #8b898f;
--amp-faint: #525055;
--amp-comment: #525055;
--amp-accent: #A67CFF;
--amp-accent-hover: #C3A7FF;
--amp-heading-accent: #C3A7FF;
--amp-green: #3fbf98;
--amp-surface: #0f1117;
--amp-surface-2: #16161c;
--amp-border: rgba(255, 255, 255, 0.1);
--amp-border-2: #1f1e24;
--amp-border-input: #2e2d33;
--amp-border-hover: #403f44;
}

.amp-home * { box-sizing: border-box; }
.amp-home h1, .amp-home p { margin: 0; font-family: inherit; color: inherit; }
.amp-home a { color: inherit; text-decoration: none; font-weight: inherit; border: 0; }
.amp-home a:hover { text-decoration: none; }
.amp-home input { font-family: inherit; }
.amp-home input::placeholder { color: var(--amp-faint); }
.amp-home [hidden] { display: none !important; }

.amp-section { margin: 0 auto; }
.amp-section--flush { margin-top: 4px; }

/* ---------- Hero ---------- */
.amp-hero {
padding: 8px 0 4px;
display: grid;
grid-template-columns: minmax(0, 1fr) minmax(0, 1.05fr);
gap: 48px;
align-items: start;
}
.amp-eyebrow {
font-size: 14px;
font-weight: 600;
color: var(--amp-accent);
margin-bottom: 10px;
}
/* Matches the docs page-title spec: text-3xl / font-bold / tracking-tight. */
.amp-home h1.amp-title {
font-size: 30px;
line-height: 38px;
letter-spacing: -0.025em;
font-weight: 700;
text-wrap: pretty;
}
.amp-title-accent { color: var(--amp-heading-accent); }
.amp-lede {
margin-top: 16px;
font-size: 16px;
line-height: 1.75;
color: var(--amp-fg-2);
max-width: 46ch;
text-wrap: pretty;
}
.amp-actions { display: flex; gap: 12px; margin-top: 24px; flex-wrap: wrap; }
.amp-btn {
display: inline-flex;
align-items: center;
height: 40px;
padding: 0 18px;
border-radius: 12px;
font-size: 15px;
transition: border-color 120ms ease, color 120ms ease;
}
.amp-btn--secondary { border: 1px solid var(--amp-border); color: var(--amp-fg); font-weight: 500; }
.amp-home a.amp-btn--secondary:hover { border-color: var(--amp-accent); color: var(--amp-accent); }
.amp-facts {
display: flex;
gap: 24px;
flex-wrap: wrap;
margin-top: 28px;
font-family: var(--amp-mono);
font-size: 13px;
color: var(--amp-muted-2);
}

/* Manifest panel, sized to match a native code block. */
.amp-manifest {
border: 1px solid var(--amp-border);
border-radius: 16px;
background: var(--amp-surface-2);
overflow: hidden;
}
.amp-manifest-bar {
display: flex;
align-items: center;
gap: 10px;
height: 40px;
padding: 0 16px;
border-bottom: 1px solid var(--amp-border-2);
font-family: var(--amp-mono);
}
.amp-manifest-file { font-size: 13px; color: var(--amp-fg); }
.amp-manifest-note { font-size: 12px; color: var(--amp-muted-2); }
.amp-yaml {
padding: 18px 20px;
font-family: var(--amp-mono);
font-size: 13px;
line-height: 1.7;
color: var(--amp-fg-2);
overflow-x: auto;
}
.amp-yaml > div { white-space: nowrap; }
.amp-i2 { padding-left: 2ch; }
.amp-i4 { padding-left: 4ch; }
.amp-i6 { padding-left: 6ch; }
.amp-i8 { padding-left: 8ch; }
.amp-i10 { padding-left: 10ch; }
.amp-i12 { padding-left: 12ch; }
.amp-k { color: var(--amp-muted-2); }
.amp-v { color: var(--amp-fg-2); }
.amp-s { color: var(--amp-green); }
.amp-d { color: var(--amp-faint); }
.amp-c { color: var(--amp-comment); }
.amp-manifest-foot {
padding: 12px 20px;
border-top: 1px solid var(--amp-border-2);
font-family: var(--amp-mono);
font-size: 12px;
color: var(--amp-muted-2);
}

/* ---------- Responsive (container-based, since the sidebar narrows the content) ---------- */
@container (max-width: 880px) {
.amp-hero { grid-template-columns: minmax(0, 1fr); gap: 32px; }
}
@media (max-width: 640px) {
.amp-home h1.amp-title { font-size: 25px; line-height: 32px; }
}
176 changes: 162 additions & 14 deletions src/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,173 @@
---
title: "Overview"
title: "Ampersand documentation"
sidebarTitle: "Overview"
description: "Build native SaaS integrations with a declarative manifest. Ampersand handles auth, field mapping, rate limits, and delivery."
mode: "wide"
---

[Ampersand](https://www.withampersand.com/) is a declarative platform for SaaS builders who are creating product integrations. It allows you to:
{/* Only the hero is custom (see /home.css). Everything else on this page uses
native Mintlify components, so it matches the rest of the docs. */}

* 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.
<div className="amp-home not-prose">

Here's an overview of the Ampersand platform:
<section className="amp-section amp-hero">
<div>
<div className="amp-eyebrow">Documentation</div>
<h1 className="amp-title">Build native integrations with a <span className="amp-title-accent">declarative manifest.</span></h1>
<p className="amp-lede">Declare what to read, write, and subscribe to in a single manifest. Ampersand handles auth, field mapping, rate limits, and delivery.</p>
<div className="amp-actions">
<a className="amp-btn amp-btn--secondary" href="/quickstart">Quickstart</a>
<a className="amp-btn amp-btn--secondary" href="/concepts">How Ampersand works</a>
</div>
<div className="amp-facts">
<span>190+ providers</span>
<span>OAuth managed</span>
<span>Deploy via CLI</span>
</div>
</div>
<div className="amp-manifest">
<div className="amp-manifest-bar">
<span className="amp-manifest-file">amp.yaml</span>
<span className="amp-manifest-note">declarative integration manifest</span>
</div>
<div className="amp-yaml">
<div><span className="amp-k">specVersion:</span> <span className="amp-v">1.0.0</span></div>
<div><span className="amp-k">integrations:</span></div>
<div className="amp-i2"><span className="amp-d">-</span> <span className="amp-k">name:</span> <span className="amp-s">crm-sync</span></div>
<div className="amp-i4"><span className="amp-k">provider:</span> <span className="amp-s">salesforce</span></div>
<div className="amp-i4"><span className="amp-k">read:</span></div>
<div className="amp-i6"><span className="amp-k">objects:</span></div>
<div className="amp-i8"><span className="amp-d">-</span> <span className="amp-k">objectName:</span> <span className="amp-s">contact</span></div>
<div className="amp-i10"><span className="amp-k">destination:</span> <span className="amp-s">contactsWebhook</span></div>
<div className="amp-i10"><span className="amp-k">schedule:</span> <span className="amp-s">{'"*/15 * * * *"'}</span></div>
<div className="amp-i10"><span className="amp-c">{'# mapped by the customer'}</span></div>
<div className="amp-i10"><span className="amp-k">requiredFields:</span></div>
<div className="amp-i12"><span className="amp-d">-</span> <span className="amp-k">fieldName:</span> <span className="amp-s">email</span></div>
<div className="amp-i12"><span className="amp-d">-</span> <span className="amp-k">mapToName:</span> <span className="amp-s">lifecycle_stage</span></div>
<div className="amp-i10"><span className="amp-k">optionalFieldsAuto:</span> <span className="amp-v">all</span></div>
<div className="amp-i4"><span className="amp-k">write:</span></div>
<div className="amp-i6"><span className="amp-k">objects:</span></div>
<div className="amp-i8"><span className="amp-d">-</span> <span className="amp-k">objectName:</span> <span className="amp-s">note</span></div>
</div>
<div className="amp-manifest-foot">
<span>$ amp deploy ./integrations --project my-app</span>
</div>
</div>
</section>

<Frame caption="The Ampersand platform">![The Ampersand platform](/images/overview.png)</Frame>
</div>

The key components include:
## Actions

* **Manifest file:** an `amp.yaml` file, where you define all your integrations: API to connect to, objects and fields you want to read or write, and configuration options you'd like to expose to your customers.
* **Ampersand server:** a managed service that keeps track of each of your customer’s configurations, and makes the appropriate API calls to your customer's SaaS, while optimizing for cost, handling retries and error message parsing.
* **Embeddable UI components** with Ampersand, you can embed set-up, configuration, and management UIs that allow your end users to customize and manage their integrations.
Actions are the verbs of every integration. You declare them in your manifest.

<Frame caption="Our React SDK offers embeddable UI components">![Our React SDK offers embeddable UI components](/images/f5c6c9b-image.png)</Frame>
<CardGroup cols={3}>
<Card title="Read" icon="download" href="/read-actions">
Scheduled or on-demand reads with incremental syncs, delivered anywhere.
</Card>
<Card title="Write" icon="upload" href="/write-actions">
Create and update records in your customer's SaaS, one at a time or in bulk.
</Card>
<Card title="Subscribe" icon="bell" href="/subscribe-actions">
React to creates, updates, deletes, and field changes as they happen.
</Card>
<Card title="Search" icon="magnifying-glass" href="/search-actions">
Targeted, synchronous queries with filters. No stored copy required.
</Card>
<Card title="Proxy" icon="arrow-right-arrow-left" href="/proxy-actions">
Call any provider endpoint directly with managed auth attached.
</Card>
</CardGroup>

* **Dashboard**: our dashboard allows you to monitor and troubleshoot your customers' integrations.
## Get started

<Frame caption="Ampersand Dashboard">![Ampersand Dashboard](/images/ef05f17-image.png)</Frame>
Three ways in, depending on how you like to learn.

<CardGroup cols={3}>
<Card title="1. How Ampersand works" icon="book" href="/concepts">
The model in five minutes: integrations, installations, revisions, and the config that decides what runs for each customer.
</Card>
<Card title="2. Build your first integration" icon="rocket" href="/quickstart">
Create a project, define a manifest, deploy it with the CLI, and embed the install UI in your app.
</Card>
<Card title="Or: clone a working app" icon="github" href="/starter-project">
A React app with HubSpot already wired up. Swap in your own manifest and deploy.
</Card>
</CardGroup>

## Guides

The hard parts, already handled.

### Reads and backfills

- [Backfill historical data on install](/read-actions#backfill-behavior): none, full history, or time-boxed per object, with an API to monitor progress.
- [Read only the records that match](/read-actions#filter-by-field-values): per-installation field filters, plus backfill-specific filters for the initial sync.

### Writes that respect customer data

- [Bulk writes with retries built in](/write-actions#write-modes): batching, async mode, and exponential backoff for up to 48 hours.
- [Never clobber customer data](/write-actions#advanced-use-cases): mark fields write-on-create-only or update-only, with defaults.

### Real-time events

- [Watch individual fields, not whole objects](/subscribe-actions#specify-fields-to-watch): subscribe to updates only for the fields you list, quota-optimized at the source.
- [Track when records are linked, not just changed](/subscribe-actions#association-changes): subscribe to association changes.
- [Get notified when integrations change](/notifications/overview): events for installs, config changes, completed backfills, and paused syncs.

### Schemas and mapping

- [Map nested and dynamic fields](/object-and-field-mapping#user-defined-mapping): nested JSON paths, value mapping, and per-customer field sets.
- [React when a customer's schema drifts](/manage-customer-schemas#watch-schema-changes): get events when fields are created, deleted, or change type.
- [Create custom fields in the customer's SaaS](/manage-customer-schemas#create-or-update-custom-fields): upsert custom fields programmatically.
- [Support multiple CRMs with one manifest](/unified-api): shared object names, per-provider overrides, no forked code.

### Running in production

- [Verify every webhook cryptographically](/destinations/webhooks#webhook-signature-verification): Svix-signed payloads, plus payload size and frequency controls.
- [Stay under provider rate limits](/proxy-actions#use-ampersand-to-manage-api-rate-limits): throttle mode returns a retry-after instead of burning 429s.
- [Call the API from the browser, safely](/api/jwt-auth): short-lived JWTs signed by your server, no API keys in frontend code.

## Reference

<CardGroup cols={2}>
<Card title="Manifest schema" icon="file-code" href="/manifest-reference">
Every field for read, write, subscribe, proxy, and field mapping in `amp.yaml`.
</Card>
<Card title="CLI" icon="terminal" href="/cli/reference">
Commands, flags, and CI usage for deploying and diffing manifests.
</Card>
<Card title="REST API" icon="code" href="/api/overview">
Installations, connections, records, and webhook payloads.
</Card>
<Card title="React SDK" icon="cube" href="/headless">
Hooks for connections, installations, and config in `@amp-labs/react`.
</Card>
</CardGroup>

## Integrations

Ampersand supports 190+ providers through one manifest surface. Each provider guide lists the supported objects, the authentication type, and whether read, write, and subscribe actions are available.

<CardGroup cols={2}>
<Card title="Browse the provider directory" icon="plug" href="/provider-guides/overview">
Search every supported provider, from Salesforce and HubSpot to NetSuite and Workday.
</Card>
<Card title="Request a provider" icon="github" href="https://github.com/amp-labs/connectors">
Missing an API you need? File an issue on the open-source connectors repository.
</Card>
</CardGroup>

## Troubleshooting and support

<CardGroup cols={3}>
<Card title="Troubleshooting" icon="wrench" href="/troubleshooting-guides/overview">
A searchable index of known errors, general and provider-specific, with step-by-step fixes.
</Card>
<Card title="Changelog" icon="clock-rotate-left" href="https://www.withampersand.com/changelog">
Manifest spec versions, provider additions, breaking changes.
</Card>
<Card title="Support" icon="life-ring" href="mailto:support@withampersand.com">
Shared Slack channel with our engineers, or email support@withampersand.com.
</Card>
</CardGroup>