1. Getting started

Prerequisites

• Node.js 20.9 or newer for the Next.js applications
• The .NET SDK required by Pumpkin API
• Access to the configured MongoDB or Cosmos DB data service
• A Pumpkin tenant ID and API key

Install and run

Start the API first, then the tenant website. Commands are run from their project directories.

# API
cd pumpkin-cms/apps/pumpkin-api
dotnet run

# Pumpkin Cloud
cd pumpkin-cloud
npm install
npm run dev

The default local addresses are API http://localhost:5064, starter app http://localhost:3003, and Pumpkin Cloud http://localhost:3004.

Website environment

NEXT_PUBLIC_PUMPKIN_API_URL=http://localhost:5064
PUMPKIN_TENANT_ID=pumpkin
PUMPKIN_API_KEY=replace-with-a-valid-key

Keep .env out of Git. API keys are used by server-side requests and must not be placed into browser code, public JSON, screenshots, or documentation examples.

Admin access

Open /admin/login. The website exchanges credentials with Pumpkin API and stores the administrator session in secure cookies. The content workspace manages pages, relationships, forms, media, navigation, and themes for the bound tenant.

2. Runtime model

The public website resolves a route to a normalized page slug. The home route requests home; a URL such as /services/design requests services/design. The website fetches the published page and active theme on the server, hydrates dynamic hub links when needed, and renders each block through BlockViewRenderer.

Pumpkin Cloud first uses a published API page. If it is unavailable, bundled JSON under content/ supplies the launch-site fallback. Production content should be published into the Pumpkin tenant; bundled files remain recovery and bootstrap content.

3. Page JSON contract

Every page has an envelope and a block array. Required areas are identity, metadata, search data, SEO, publishing state, relationships, and ContentData.ContentBlocks.

{
  "id": "about",
  "PageId": "about",
  "tenantId": "tenant-id",
  "pageSlug": "about",
  "PageVersion": 1,
  "Layout": "default",
  "MetaData": { "title": "About", "description": "..." },
  "searchData": { "keyword": "...", "tags": [], "blockTypes": [] },
  "seo": { "metaTitle": "...", "robots": "index, follow" },
  "isPublished": true,
  "includeInSitemap": true,
  "contentRelationships": { "isHub": false, "hubPageSlug": "home" },
  "ContentData": { "ContentBlocks": [] }
}

Identity and routing

• pageSlug is lowercase and has no leading slash.
• Use nested slugs for nested routes.
• Keep id and PageId stable across revisions.
• Increment PageVersion when producing a new version.

Metadata and SEO

MetaData describes the page inside Pumpkin. seo controls search and social output. Set a unique title and description, a canonical URL, intentional robots behavior, Open Graph values, and sitemap inclusion. Legal drafts should remain noindex until approved.

Relationships

A hub page sets isHub to true. A spoke page names its hubPageSlug and can set spokePriority. The HubSpokes block queries published pages connected to that hub.

4. HTML block reference

Every block has type and content. The editor also stores id, name, and enabled. Keep IDs stable and unique within a page.

Hero

Use once near the top of a page. Fields: type, headline, subheadline, background image fields, main image fields, and button text/link. Image presentation accepts aspect, fit, and position.

{ "type": "Hero", "content": { "type": "Main", "headline": "Clear outcome", "subheadline": "Supporting promise", "backgroundImage": "", "mainImage": "", "buttonText": "Start", "buttonLink": "/signup" } }

PrimaryCTA

A prominent conversion section with primary and secondary actions. Fields: title, description, button text/link, secondary text/link text/link, background image, main image, and alt text.

{ "type": "PrimaryCTA", "content": { "title": "Ready?", "description": "Take the next step.", "buttonText": "Start", "buttonLink": "/signup", "secondaryText": "Need details?", "secondaryLinkText": "Read docs", "secondaryLink": "/docs", "backgroundImage": "", "mainImage": "", "alt": "" } }

SecondaryCTA

A compact call to action. Fields: title, description, button text, and button link.

{ "type": "SecondaryCTA", "content": { "title": "Need help?", "description": "Tell us what you are building.", "buttonText": "Contact us", "buttonLink": "/contact" } }

CardGrid

Use for features, services, choices, or linked resources. Fields: title, subtitle, layout, optional image presentation, and cards. Each card includes title, description, image, image-alt, icon, link, and alt.

{ "type": "CardGrid", "content": { "title": "Features", "subtitle": "What is included", "layout": "grid-3", "cards": [{ "title": "Managed SSL", "description": "Certificate binding handled for you.", "image": "", "image-alt": "", "icon": "Lock", "link": "/managed-hosting", "alt": "" }] } }

FAQ

Use for genuine objections and recurring questions. Fields: title, subtitle, layout, and items with question/answer.

{ "type": "FAQ", "content": { "title": "Questions", "subtitle": "Before you start", "layout": "accordion", "items": [{ "question": "Can I use my domain?", "answer": "Yes." }] } }

HubSpokes

Displays published spoke pages related to a hub. Fields: title, subtitle, hubPageSlug, layout, limit, showExcerpt, showLocation, ctaText, and spokes. The website replaces spokes with API results at render time.

{ "type": "HubSpokes", "content": { "title": "Related guides", "subtitle": "", "hubPageSlug": "docs", "layout": "cards", "limit": 12, "showExcerpt": true, "showLocation": false, "ctaText": "Read guide", "spokes": [] } }

Breadcrumbs

Shows route context. Fields: items with label, URL, and current state.

{ "type": "Breadcrumbs", "content": { "items": [{ "label": "Home", "url": "/", "current": false }, { "label": "Docs", "url": "/docs", "current": true }] } }

TrustBar

Use for concise proof points or platform attributes. Fields: items with icon, title, text, and alt.

{ "type": "TrustBar", "content": { "items": [{ "icon": "ShieldCheck", "title": "Managed SSL", "text": "HTTPS included", "alt": "" }] } }

HowItWorks

A sequential process. Fields: title and steps with title, text, image, and alt.

{ "type": "HowItWorks", "content": { "title": "Launch steps", "steps": [{ "title": "Create", "text": "Build the page.", "image": "", "alt": "" }] } }

ServiceAreaMap

For geographic service pages. Fields: title, subtitle, mapEmbedUrl, neighborhoods, zipCodes, and nearbyCities. Only use trusted embed URLs and avoid unnecessary third-party tracking.

{ "type": "ServiceAreaMap", "content": { "title": "Service area", "subtitle": "Where we work", "mapEmbedUrl": "", "neighborhoods": [], "zipCodes": [], "nearbyCities": [] } }

LocalProTips

Reusable advice cards for service or location pages. Fields: title and items with icon, image, title, and text.

{ "type": "LocalProTips", "content": { "title": "Local tips", "items": [{ "icon": "Lightbulb", "image": "", "title": "Plan ahead", "text": "Useful local guidance." }] } }

Gallery

Displays owned or licensed media. Fields: title, subtitle, image presentation, and images with src, alt, and caption.

{ "type": "Gallery", "content": { "title": "Gallery", "subtitle": "", "imageAspect": "4:3", "imageFit": "cover", "imagePosition": "center", "images": [{ "src": "https://...", "alt": "Useful description", "caption": "Optional caption" }] } }

Testimonials

Use only real, approved customer statements. Fields: title, subtitle, layout, and items with quote, author, eventType, and rating.

{ "type": "Testimonials", "content": { "title": "Customer results", "subtitle": "", "layout": "grid", "items": [{ "quote": "Approved quote", "author": "Customer name", "eventType": "Managed website", "rating": 5 }] } }

Contact

Displays contact details and an inline form definition. Add formType when submissions should post to Pumpkin forms. Fields include title, subtitle, address, phone, email, hours, formFields, submit text, and social links.

{ "type": "Contact", "content": { "id": "contact", "formType": "contact", "title": "Contact us", "subtitle": "", "address": "", "phone": "", "email": "hello@example.com", "hours": "", "formFields": [{ "label": "Email", "type": "email", "required": true, "placeholder": "you@example.com" }], "submitButtonText": "Send", "socialLinks": [] } }

Form

References a reusable Pumpkin FormDefinition by formType. Fields: formType, title, subtitle, description, layout, and successMessage. The definition supplies fields, validation, submit text, and behavior.

{ "type": "Form", "content": { "formType": "contact", "title": "Send a message", "subtitle": "", "description": "", "layout": "default", "successMessage": "Thanks." } }

Blog

Renders an article, guide, policy, or manual. Fields include title, subtitle, author metadata, publication date, featured image, excerpt, HTML body, tags, categories, reading time, image presentation, and relatedPosts. The starter strips scripts, iframes, objects, embeds, event handlers, JavaScript URLs, and inline styles from body HTML.

{ "type": "Blog", "content": { "title": "Guide title", "subtitle": "", "author": "Team", "authorImage": "", "authorBio": "", "publishedDate": "2026-07-14", "featuredImage": "", "featuredImageAlt": "", "excerpt": "Summary", "body": "<p>Article HTML</p>", "tags": [], "categories": [], "readingTime": 5, "relatedPosts": [] } }

5. Media and images

Upload tenant media through the content admin and use its public URL in block content. Always supply meaningful alt text unless an image is purely decorative. Supported presentation values are aspect auto, square, 4:3, 16:9, or 21:9; fit cover or contain; and position center, top, bottom, left, or right.

6. Themes and navigation

The active theme supplies header settings, footer settings, menu items, typography, CSS variables, and class-name maps for blocks. A compiled theme may also provide a CSS URL and integrity value. Keep navigation URLs aligned with published page slugs. Test desktop dropdowns, mobile navigation, focus behavior, custom-domain asset loading, and fallback CSS before activating a theme.

7. Content workflow

1. Create or edit the page in the tenant content admin.
2. Confirm the slug, metadata, SEO, block order, links, image rights, and alt text.
3. Preview forms and interactive blocks.
4. Publish the page.
5. Trigger revalidation when an immediate refresh is required.
6. Verify the canonical production URL on desktop and mobile.

The JSON files in Pumpkin Cloud are bootstrap and fallback content. Update them when a production-critical page needs a recovery copy, but treat the published Pumpkin tenant as the ordinary editorial source.

8. Routes

home maps to /. Other slugs map directly to their path. Avoid collisions with application-owned routes such as /signup, /pricing, /admin, and /api. Those flows remain code-owned even when surrounding marketing copy is CMS-driven.

9. Production and custom domains

Production deployment requires server-side API URL, tenant ID, and API key settings. Pumpkin Cloud also requires a production signup provider before checkout or provisioning can be enabled. Validate the default Pumpkin hostname first. Then complete custom-domain ownership validation, DNS changes, certificate readiness, canonical URLs, redirects, and analytics configuration.

10. Accessibility checklist

• Use one clear page heading.
• Keep heading levels in a logical order.
• Write descriptive link text.
• Provide useful image alt text.
• Do not encode essential information only in color or images.
• Test menus, accordions, forms, and dialogs with a keyboard.
• Confirm visible focus and adequate contrast in the active theme.

11. Adding a custom block

A custom block is a product feature, not merely new JSON. Add a shared TypeScript model, export it from the block union, implement its React view and defaults, add it to BlockViewRenderer, expose editor support, add theme class names and CSS, document its schema, rebuild and publish shared packages, and test existing tenants for compatibility.

12. Troubleshooting

Port already in use

Find and stop the stale Node or .NET process using the expected port. Do not terminate unrelated system services.

Cannot resolve pumpkin-block-views

Run npm install in the website project. If the repository moved, local package junctions may still target the old path and need to be recreated.

Theme CSS does not load

Inspect the rendered stylesheet URL, response status, browser console, CORS behavior, and integrity metadata. Cross-origin SRI requires an approved CORS response. Confirm the blob exists and that the active theme points to the intended version.

Menu opens incorrectly

Confirm the application and block-view package resolve one React runtime. Multiple React versions can break hook-driven components during hydration.

Hero image is missing

Check the API page JSON, public media URL, active theme class, image aspect/fit/position, browser network response, and alt text. The Hero view uses mainImage for an inline image and backgroundImage for a CSS background.

Page returns 404

Verify the normalized slug, publication state, tenant ID, API credentials, and API response. In Pumpkin Cloud, confirm the slug is also present in the fallback registry if offline rendering is expected.

Form does not submit

Confirm the block's formType, matching FormDefinition, API availability, field names, validation, and tenant authorization. Browser-visible fields do not prove the server definition exists.

Content appears stale

Verify the API record first, then trigger the admin revalidation endpoint or wait for the configured revalidation interval. Confirm you are testing the correct tenant and domain.

Verification commands

npm run type-check
npm run lint
npm run build
npm audit --omit=dev

13. Page recipes

Service homepage: Hero, TrustBar, CardGrid, HowItWorks, Testimonials, FAQ, Contact.

Product landing page: Hero, TrustBar, CardGrid, Gallery, PrimaryCTA, FAQ, Form.

Service detail: Breadcrumbs, Hero, CardGrid, LocalProTips, Testimonials, SecondaryCTA.

Location page: Breadcrumbs, Hero, ServiceAreaMap, LocalProTips, FAQ, Contact.

Resource hub: Hero, CardGrid, HubSpokes, SecondaryCTA, FAQ.

Article: Breadcrumbs, Blog, PrimaryCTA.