Site Builder

How Ploy sites are built, structured, and styled.

Every Ploy site runs on a modern web stack — Astro, React, TypeScript, and Tailwind CSS. You don't need to know any of this to use Ploy. Ploy's Agent handles the implementation. This page explains how things work under the hood for users who want to understand the architecture or make manual edits.

How Sites Are Structured

A Ploy site is organized into pages, sections, and components:

Example Structure

src/
├── pages/
│   ├── index.astro        (homepage)
│   ├── about.astro         (about page)
│   └── pricing.astro       (pricing page)
├── sections/
│   ├── Hero.tsx
│   ├── Features.tsx
│   ├── Testimonials.tsx
│   └── Pricing.tsx
└── components/
    ├── Button.tsx
    ├── Card.tsx
     └── Badge.tsx

Design System

Your brand's visual identity is stored as a design system — a set of tokens that control colors, typography, spacing, border radius, and shadows across your entire site.

What's Included

• Colors — Primary, secondary, accent, neutral, and semantic colors in light and dark mode.
• Typography — Heading and body font families, weights, and a type scale from xs to 9xl.
• Spacing — Consistent spacing tokens for margins, padding, and gaps.
• Border Radius — Configurable for buttons, cards, inputs, and global defaults.
• Shadows — Shadow color and elevation tokens.

How It Works

The design system is defined in your workspace and compiled into CSS custom properties (Tailwind theme tokens). Every section and component references these tokens, so changing a color in your design system updates it everywhere instantly.

Updating Your Design System

• From chat: Ask Ploy's Agent — "Change our primary color to navy blue" or "Use Inter for headings."
• From Figma: Connect a Figma file and Ploy's Agent will extract your brand tokens automatically.
• From a website: When you clone a site, Ploy extracts the design system from the source.

Creating Pages

Ask Ploy's Agent to create a page and it'll handle the rest:

• "Add an about page with our team story, values, and a team photo grid"
• "Create a pricing page with three tiers: Free, Pro, and Enterprise"
• "Build a blog with posts from our Notion database"

Ploy's Agent will create the page file, build or reuse sections, apply your design system, and add it to your site's navigation if appropriate.

Adding Search to Your Site

This guidance is for adding search to a site you build with Ploy.

We strongly recommend Pagefind for adding search to static Ploy sites. It scans your site's generated HTML after each build, creates a compact search index, and runs queries in the visitor's browser without requiring a hosted search service or database.

Pagefind's Component UI provides accessible, customizable search modals and search boxes that can be added with standard HTML, JavaScript, and CSS. Other search libraries will also work, provided they support sites built with standard HTML, JavaScript, and CSS.

Example prompt: “Add full-text search to my Ploy site using Pagefind's Component UI. Index all published page content, add an accessible search trigger to the site header, support ⌘K and Ctrl+K, style it to match my design system, and generate the search index during production builds.”

Cloning Sites

Ploy can clone an existing website from a URL:

• Full site clone — Imports the entire site's design, content, and structure, plus extracts the brand design system.
• Page clone — Import a specific page from any URL into your site.
• Section clone — Grab a specific section (hero, nav, footer) from any page and add it as a reusable component.

Tip: Cloning a competitor's site and then asking Ploy's Agent to adapt it to your brand is one of the fastest ways to get started.

FAQ — External Content

Serving Existing Static HTML Assets

Yes — we can import your existing static HTML assets. Just ask Ploy's Agent to serve them from the project's publicDir. See more in the Astro publicDir configuration reference.

If your static HTML assumes it is served from a base URL, any absolute paths for referenced resources may need to be adjusted to match the Ploy project's file layout.

Client-Side Scripts

Yes — anything that works with a normal web page will work with Astro, including third-party analytics scripts and graphics-processing libraries such as Three.js. See the Astro client-side scripts guide for more details.

Bringing an Outside Repo

We do not recommend bringing in an outside repo built with an arbitrary framework. It may not be compatible with Ploy's hosting infrastructure, and we cannot guarantee a successful conversion.

Attempting to convert an outside project to Astro is also less token-efficient than asking Ploy to slurp your site. Just give us the URL, and Ploy can rebuild it to our specifications.

Bringing in Public Git Repos as Context

Any publicly accessible Git repository from a major provider — including GitHub, GitLab, and Bitbucket — can be brought in as context. This is useful when your project depends on, or you want to vendor source from, a third party.

One way to do this is to ask Ploy's Agent to bring in the publicly available repository using its HTTPS URL as a new git submodule. From there, your site edits can reference the submodule because it is available in the same sandbox.

Preview & Iteration

Every site has a live preview in the dashboard that updates in real time as Ploy's Agent makes changes. You can:

• See desktop and mobile views
• Click through pages
• Watch changes appear as Ploy's Agent implements them
• Take screenshots for review

What's Next?

• Go live — Read Publishing & Deploys to understand how publishing works.
• Track performance — Set up Analytics & Visitors to monitor traffic and identify visitors.
• Connect your tools — See Integrations to link Figma, GitHub, and more.