Site Builder

Site Builder is the visual authoring surface for your public-facing site. It controls page layout, block composition, motion design, and live publishing. Changes in the builder are staged until you explicitly publish.

Site Configuration Surfaces

• Site Settings: name, language, branding, domain, and core tenant settings.
• Site Builder: page preview, edit mode, page layout, blocks, navigation, motion, and theme controls.
• Commerce: product catalog, order, and storefront management when commerce mode is enabled.
• Newsletter: audience management, campaign creation, sender setup, and campaign performance.

The saved site language is used by public-site chrome as well as generation workflows. Default navigation labels, legal/footer labels, newsletter copy, contact forms, and template fallback text should render in the tenant language unless a block or page setting provides custom copy.

Preview and edit mode are intentionally separate:

• Preview mode is a neutral review surface for staging or production. It uses the tenant preview route inside a plain iframe and avoids builder-only borders, glow shadows, sticky edit chrome, and loading accents.
• Edit mode keeps the full builder shell, block controls, selection borders, property panels, and motion/edit affordances.

Use preview mode when validating what readers will see; use edit mode only when actively changing blocks, layouts, or page chrome.

Site Modes

PromptPress supports three site modes:

• news — editorial homepage, category pages, article detail, live feeds
• ecommerce — product catalog, checkout, and commerce pages
• hybrid — combines news editorial and commerce

Mode affects available pages, blocks, and publishing behavior. You can switch mode in Site Settings.

Page Blocks

Your page is built from a sequence of blocks. Each block is a self-contained content section with its own layout, data query, and motion settings.

Block Types

Blocks support live CMS data queries (filter_type, limit, sort), layout variants (layout_width, display_variant), and motion settings.

Canvas Block

The canvas block is a freeform visual layer for landing-style sections that sit outside the CMS article feed. Instead of querying content articles, you compose the section directly from canvas elements:

• Heading — large display text with color, gradient, weight, size, and font controls
• Text — paragraph/body text with the same style options
• Button — CTA with label, link, and variant controls
• Badge — small label pill for tags or labels
• List — bulleted or numbered list with editable items

Each element has its own Layout, Layer, and Style control panels, accessible from the atom toolbar when the element is selected in the builder. Double-click any text element to edit its content inline.

Canvas blocks support a background media layer (image or video) with edge-feather, overlay opacity, frame mode (full-bleed, contained, framed), height, radius, and shadow controls.

Recommended Page Compositions

Modern News Homepage (NYT / BBC style)

1. breaking-news — urgent strip at the very top
2. hero-splash — cinematic lead story
3. topic-row × 2 — key editorial sections
4. article-grid — latest stories grid
5. dense-list — compact latest rundown

Apple / Verge — Premium Editorial

1. hero-splash with pinned scroll parallax
2. article-grid with stagger-fade on scroll
3. topic-row with slide-in
4. dense-list calm

Sports / Live Event

1. breaking-news — match alerts
2. live-feed — real-time ticker
3. hero-power — bold match feature
4. article-grid — match reports

Properties Panel

When a block is selected in the builder, the properties panel opens on the right. It shows that block's content, layout, and motion controls.

Responsive Preview

The builder toolbar includes a viewport switcher — toggle between Desktop and Mobile to check how your blocks render at different screen widths without leaving the editor.

Reset Controls

The properties panel includes a Reset dropdown with two options:

• Reset Block to Default — discards all settings and content for the selected block and restores it to the block-type factory defaults. A confirmation dialog appears before the reset runs.
• Revert to Published — replaces the current draft state with the last published snapshot of that block. Use this to undo edits since your last publish without rolling back the whole page.

Both actions are irreversible once confirmed. The confirmation dialogs have a Cancel option if you change your mind.

AI Motion Builder

The AI Motion Builder is a conversational design assistant built into the builder. Describe the visual effect you want in plain language and it generates the full motion configuration.

How to Open It

Click the sparkle (✨) button in the Site Builder toolbar. The AI Motion panel opens on the right side.

What You Can Ask

• “Apple-like parallax scroll for the hero”
• “GitHub homepage: cards that stagger fade-up on scroll”
• “Sentry marketing cinematic hero with depth zoom”
• “Suggest new blocks to complete this page like a modern news homepage”
• “Add a live-feed block and a breaking-news strip at the top”
• “Calm, minimal — barely-there entrance animations”

What It Does

• Modifies existing blocks — understands your current page structure and updates only the blocks you ask about. Content and queries are preserved.
• Creates new blocks — if your page is missing blocks that fit the requested style, it suggests adding them at the right position.
• Full page overhaul — ask to “make it like a modern news homepage” and it updates existing blocks and proposes new ones to match the composition.

Motion Presets

After the AI responds, click Apply to stage changes. Use the undo/redo arrows inside the panel to step back through AI-applied history.

Visual Animation Editor

For blocks that contain animated elements, the properties panel includes a Visual animation editor button. This opens a timeline-based editor where you can control keyframe timing, easing, and sequencing for individual block elements — independent of the AI Motion Builder.

Use the AI Motion Builder when you want to describe an effect in plain language. Use the Visual Animation Editor when you need precise per-element timeline control.

Reader Engagement: Daily Games

Your site includes Daily Sudoku and Daily Crossword — free, browser-playable games that refresh every day, accessible to all readers without an account.

Daily Sudoku (/games/sudoku)

• 4 difficulty levels: Easy, Medium, Hard, Expert
• Timer, mistake counter, hint reveals, note mode
• Daily leaderboard with anonymous participation
• Full mobile support — tap a cell, use the on-screen digit pad
• Scales to fill the full viewport on phones and tablets

Daily Crossword (/games/crossword)

• Daily puzzles across Easy, Medium, Hard difficulty
• Tap a cell to select and highlight the active word; tap again to switch Across ↔ Down
• Mobile keyboard — tapping any cell opens your phone’s keyboard automatically
• Reveal Letter hint and Erase controls
• Cursor auto-advances to the next empty cell after each letter

Disabling Games

In Site Settings → Features, set sudoku_enabled: false or crossword_enabled: false to hide the routes entirely.

Recommended Editing Flow

1. Confirm target workspace and site mode.
2. Update Site Settings first (branding, language, domain).
3. Edit page blocks and layout in Site Builder.
4. Use the AI Motion Builder to configure animations.
5. Review the embedded staging or production preview on both desktop and mobile. The preview should look like the public tenant site, not the editor canvas.
6. Open the preview in a new tab for any mutation-heavy checks.
7. Publish live when checks pass.

Commerce Organization

The Commerce organize view manages product categories, tags, and collections from one workspace surface.

• Each taxonomy card opens into a focused management panel with counts, active/archive filters, and create forms.
• The add form starts collapsed with a plus icon. Once expanded, the same control changes to an X icon and Hide form label.
• Categories, tags, and collections can be archived and restored without deleting their product relationships.
• Product edit dialogs use the active taxonomy lists for product classification and storefront grouping.

Use categories for primary navigation, tags for flexible filtering, and collections for curated storefront groupings.

Newsletter Performance

The Newsletter manager shows performance inside Past Campaigns rather than as a separate stats page.

• The top of Past Campaigns includes overall KPI cards for sent campaigns, recipients, delivered/sent volume, opens, clicks, bounces, and delivery health.
• The campaign list is paginated for longer histories.
• Individual past campaigns can be expanded to inspect delivery, open, click, bounce, suppression, and failure metrics.
• Metrics are derived from tenant_newsletter_campaigns and tenant_newsletter_deliveries.

Open and click rates are calculated against delivered mail when delivery data is available, with sent count used as a fallback denominator.

Newsletter Composer UX

The Newsletter workspace is organized into Create, Preview, Past Campaigns, Audience, and Settings tabs. The tab bar should render as a rounded horizontal control with a background that matches the control's size and shape.

In the composer:

• Generate with AI starts guided or article-driven drafts.
• Build manually opens the editable subject, preview text, section list, template, starter pack, theme, reuse, and send controls.
• Theme opens a single modal for preset and custom colors. The More preset toggle expands the preset grid inside the same modal and must not stack another modal beneath it.
• Preview Current switches to a read-only rendered newsletter preview before saving, scheduling, or sending.

Step-by-Step: First Live Site Publish

1. Open Site Settings and confirm site name, language, and brand basics.
2. Open Site Builder, use preview mode for review, then enter builder/edit mode for changes.
3. Make one focused layout/content change.
4. Save changes.
5. Preview home, category/listing, and article/detail routes.
6. Publish live.
7. Verify the same routes in an incognito window.

Step-by-Step: Add a Block to a Page

1. Open Site Builder and select the target page.
2. Click Add Block and choose a block type.
3. Configure the block’s data query (filter, limit, sort).
4. Optionally open the AI Motion panel to add entrance animations.
5. Save and preview.
6. Publish when ready.

Step-by-Step: Domain Readiness Check

1. Confirm target domain and DNS records.
2. Confirm domain verification status in Site Settings.
3. Publish a small visible change.
4. Validate the change on both default domain and custom domain.
5. If mismatch appears, wait for propagation and re-check.

Template and Page Strategy

For most teams:

• Start with home, category/listing, and article/detail templates.
• Add custom pages only when they support a clear user journey.
• Use one purpose per custom page to keep maintenance simple.

Navigation and Theme Governance

• Keep navigation structure stable across releases.
• Test color contrast before publishing.
• Avoid changing nav, theme, and major content in one release.

Theme Packs and Color Editing

Site Settings groups starter themes into light and dark theme packs. Selecting a pack applies the paired light/dark color palettes and theme style while preserving the active brand typography, spacing, and radius choices.

Use the theme color editor after selecting a pack when you need a local adjustment. The editor changes the active theme colors, while the theme pack picker remains the fastest way to switch between complete light/dark palette sets.

Domain and Launch Readiness

Before announcing a new section or redesign:

• Verify domain and DNS status.
• Confirm header/footer visibility rules.
• Validate desktop and mobile rendering.
• Re-check primary routes after publish.

Common Issues

Step-by-Step: Request a Newsletter Sending Domain

By default newsletters send from the shared SaaS domain. If you want a branded sender address (e.g. [email protected]), request a platform-managed domain. The platform admin registers the domain in Resend and returns the DNS records you need to add.

1. Open Site → Newsletter.
2. Go to the Settings tab inside the newsletter manager.
3. Under Sender mode, select Request platform-managed sender domain.
4. In Sender domain, enter the subdomain you want to send from — typically mail.yourdomain.com.
5. In Sender local-part, enter the part before the @ (e.g. newsletter). The resolved sender preview updates in real time.
6. Click Request / Update Domain. Your request enters the super admin queue.
7. The admin registers the domain in Resend and adds DNS records to your request.
8. Return to the Newsletter Settings panel and click Verify / Refresh to load the DNS records provided by the admin.
9. Add each DNS record (TXT, CNAME, or MX as shown) to your domain registrar.
10. Click Verify / Refresh again. Status changes to Verified once all records propagate.

Note: Propagation can take a few hours. If the status stays unverified after 12 hours, check the Admin notes field for any additional instructions, and confirm the records are published by querying DNS directly.

Step-by-Step: Request and Enable Ad Integration

Ad integration is admin-mediated: you submit the request and the admin configures DNS TXT verification, uploads your ads.txt, and sets ad zones. Once the admin marks your setup Ready, you control which articles show ads and at what density.

1. Open Site → Site Settings.
2. Scroll to the Ad Integrations section.
3. Click Request Ad Integration. A confirmation banner appears: "Your request is now in the super admin queue."
4. Wait for the admin to process the request. They will add DNS TXT/meta verification, upload ads.txt, and configure ad zones for your domain. Status moves through: Requested → Verification added → Scripts configured → Ready.
5. When status shows Ready, return to Site Settings.
6. In the Article ad density panel, choose how aggressively ads appear in articles:
   • Off — no in-article ads (use this while awaiting admin setup)
   • Light — minimal insertions, least intrusive
   • Medium — balanced (recommended for most publications)
   • Heavy — maximum insertions
7. Click Save Settings.
8. Publish a test article and confirm ads render at the expected positions on the public site.

Note: Ad scripts render only on public tenant pages. They are never injected into checkout, auth, admin, or SaaS routes. If your request is Rejected, contact the admin for the reason before re-requesting.

The advertiser-facing portal now browses public article and category pages on the advertiser origin itself, so live publisher links open in a new tab while internal preview stays on the same host. Campaign setup also supports a visual slot picker, all page types, and specific-domain targeting for networked tenants.

Related Docs

• Getting Started
• Content Creation
• Troubleshooting