Pantheon P1 Developer Docs

Working documentation for building on Pantheon’s P1 platform: written by Prolific Digital while rebuilding Herradura for Brown-Forman on Pantheon’s infrastructure.

Why this exists

P1 is in alpha. Pantheon’s own documentation is thin in places, and we’re finding gaps, quirks, and undocumented behavior as we go. Rather than let that knowledge live only in Slack threads and one developer’s head, we’re writing it down here, so anyone on the team (or the next agency partner Pantheon brings on) can pick up a P1 project and get productive fast, without re-discovering the same things the hard way.

This is our documentation, not Pantheon’s. When something here turns out to be wrong, outdated, or Pantheon ships an official doc that supersedes it, update or cut the page.

Who this is for

Written for developers coming from WordPress or Drupal, since that’s most of our team’s background and P1 doesn’t have an established body of “getting started” knowledge the way those platforms do. Where a P1 concept has a reasonably close analog in WordPress or Drupal, we call it out: not because the platforms work identically, but because it’s the fastest way to build a mental model.

Where to start

Getting Started: scaffold a new P1 site, connect it to a dashboard-created site, get the local editor running.
Concepts, mapped to WordPress & Drupal: what a “Site,” a “Template,” a “Component,” and the Puck editor actually are, framed against what you already know.
Outstanding Questions: every real open question from across this documentation, grouped by feature, for the team to work through together. Everything checkable against the codebase already has been; what’s left needs a person.

Core features: what P1 actually does

Workflows: how draft autosave, Publish, workstreams/merging, and content-type migration actually work, verified against the SDK source.
Permissions & Roles: the four real content roles (admin/editor/author/junior-editor), what each can and can’t do, and how a role gets assigned.
Fields Reference: every field type available when building a custom component, with real examples.
Components Reference: the components the starter kit ships with out of the box.
Data Sources & Queries: the {{ }} binding system, auto-generated per-Template queries, and the editor’s own Data Sources panel.
Media Library: the built-in p1-media plugin, basic vs. rich mode, transforms, editorial constraints, limits, and why the picker doesn’t show up on every image field in this project specifically.
SEO & GEO: real, native per-page metadata support, plus what’s different about optimizing for AI answer engines. The gaps (sitemap, structured data, redirects) are tracked separately, below, not on this page.
API Keys & Secrets: third-party credentials work like Vercel, not like a CMS. Next.js environment variables at the hosting layer, never Puck document content.
Deployment & Environments: Dev/Test/Live, Git-tag-triggered deploys for Next.js sites specifically, and cross-environment CORS.

Missing features: what P1 doesn’t do (yet), and our plan for each

Sitemap, Structured Data & Redirects: the specific SEO/GEO gaps that can actually block a launch, confirmed absent or unwired, tracked here instead of buried inside the SEO page.
Media: Bulk Management & a Library View: the media library itself works; there’s just no way to see or manage the whole thing at once. What a real fix would take, including a drafted plugin.
Managing the Header & Footer: there’s nothing built in; how to build it on the primitives P1 does give you.
Form Builder: no native end-user form builder either; the plan for a generic, editor-configurable form component, plus durable submission storage as its subpage.
Email Delivery: decoupled transactional email, since P1 has no email-sending capability natively.
Analytics & Tracking: no native analytics concept either; what a real Brown-Forman brand site runs today and the plan to package it.
Localization: no native content-i18n mechanism; how a real multi-locale P1 site actually does it, and the pattern to build on.
Content Relationships: no native way to pick “these 3 cocktails” for a Product page; no picker field, but a real extensibility primitive (Remote Datasources) a custom mechanism could build on.
Site Search: no search capability anywhere in the SDK; what building it would take.
Known Issues & Platform Quirks: things that cost us time so they don’t cost you time too, plus the consolidated index of every gap above.

Brand work

Brown-Forman: systems every Brown-Forman brand site needs (age gate, cookie consent, forms, retail locator), planned once for reuse.