Building from Scratch

This guide walks you through building a complete Primo site from scratch. You’ll create multiple page types, build several blocks, and set up a site that’s ready for content editors to use.

If you’re looking for a faster introduction, check out the Quickstart guide first.

Watch the workflow

Create a site from a starter

Watch the workflow in Primo.

Download video · Download captions

Read the walkthrough

Choose Create Site from the dashboard.
Give the new site a name.
Browse starters in the Marketplace.
Choose Hawthorn Veterinary and review its design.
Review optional blocks, then create your site.
Your new site is ready in the dashboard.

Overview

By the end of this guide, you’ll have:

A site with two page types you create: General Page and Blog Post
Five reusable blocks (Hero, Text, Image, Card Grid, Footer)
A working navigation system
Content ready for editors to manage

Download the complete example

Download the first site workspace to compare the finished blocks, fields, page types, and content with this guide. Extract the ZIP into its own folder. After installing primo-cli, run from the extracted folder:

primo validate
primo add first-site
primo dev --author files

Open the editor URL printed by the CLI and verify the sample pages. This first run imports the source and any library blocks. The editor is read-only in files mode. To edit in the browser, stop it with Ctrl+C, then run primo dev --author cms. The included README explains the field connections and differences from the browser tutorial. Use a copy if you want to keep the original example.

Prerequisites

Primo installed and running (Installation guide)
Basic familiarity with HTML, CSS, and JavaScript
Understanding of core concepts

Step 1: Create Your Site

Initialize the site

When you first access Primo, create a new site. Give it a descriptive name like “My First Site”.

The site name is for internal organization. You can change it later in settings.

Configure basic settings

Navigate to Site Settings and configure:

Site name: An internal name for the dashboard
Domain: Connect a hostname through the dashboard
Site fields: Add global branding and navigation content as needed

You can always update these settings later. For now, focus on getting the structure in place.

Step 2: Build Your Component Library

Create five example blocks in the server’s Library: Hero, Text, Image, Card Grid, and Footer. These are names for the Svelte blocks you build below, not built-in block presets. Text and Image are also field type names; the blocks here use those fields to create page sections. A Hero is an introductory section with a headline and button. A Card Grid repeats a card design for several items. You can choose other names and designs for your own sites.

Block 1: Hero

The Hero block will be the first thing visitors see on your homepage.

Create the Hero block

Open Library → Create Block. Name it “Hero”.

Write the component

<section class="hero" style={background_image?.url ? `background-image: url(${background_image.url})` : ''}>
  <div class="hero-content">
    <h1>{headline}</h1>
    <p>{subheadline}</p>
    {#if cta_link}
      <a href={cta_link} class="cta-button">{cta_text || "Learn more"}</a>
    {/if}
  </div>
</section>

<style>
  .hero {
    min-height: 60vh;
    display: flex;
    align-items: center;
    justify-content: center;
    background: linear-gradient(135deg, #4f46b6 0%, #764ba2 100%);
    background-size: cover;
    background-position: center;
    color: white;
    text-align: center;
    padding: 4rem 2rem;
  }
  
  .hero-content {
    max-width: 800px;
  }
  
  .hero h1 {
    font-size: 3.5rem;
    margin-bottom: 1rem;
    font-weight: 700;
  }
  
  .hero p {
    font-size: 1.5rem;
    margin-bottom: 2rem;
    opacity: 0.95;
  }
  
  .cta-button {
    display: inline-block;
    padding: 1rem 2.5rem;
    background: white;
    color: #4f46b6;
    text-decoration: none;
    border-radius: 0.5rem;
    font-weight: 600;
    font-size: 1.1rem;
    transition: transform 0.2s, box-shadow 0.2s;
  }
  
  .cta-button:hover {
    transform: translateY(-2px);
    box-shadow: 0 10px 25px rgba(0, 0, 0, 0.2);
  }
  
  @media (max-width: 768px) {
    .hero h1 {
      font-size: 2.5rem;
    }
    .hero p {
      font-size: 1.25rem;
    }
  }
</style>

Add fields

Add these content fields:

headline (Text) - Main headline
subheadline (Text) - Supporting text
cta_text (Text) - Button text
cta_link (URL) - Button destination URL
background_image (Image, optional) - Background image URL

The component is already set up to use these fields. Just add them in the field editor.

Your Hero block is complete and saved to your component library. It’s ready to use on any page type.

Block 2: Text

A simple text block for content sections.

Create the Text block

Create a new block called “Text”.

Write the component

<section class="text-block" class:text-center={alignment === "center"} class:text-right={alignment === "right"}>
  {@html content || ""}
</section>

<style>
  .text-block {
    max-width: 800px;
    margin: 0 auto;
    padding: 3rem 2rem;
    line-height: 1.8;
  }

  .text-block.text-center { text-align: center; }
  .text-block.text-right { text-align: right; }
  
  .text-block :global(h2) {
    font-size: 2rem;
    margin-top: 2rem;
    margin-bottom: 1rem;
  }
  
  .text-block :global(p) {
    margin-bottom: 1.5rem;
  }
  
  .text-block :global(ul), .text-block :global(ol) {
    margin-bottom: 1.5rem;
    padding-left: 2rem;
  }
  
  .text-block :global(li) {
    margin-bottom: 0.5rem;
  }
</style>

Add fields

Add these fields:

content (Rich Text) - The main content
alignment (Select) - Options: “left”, “center”, “right”

Save the Text block and check it with formatted sample content.

Block 3: Image

A block for displaying images with optional captions.

Create the Image block

Create a new block called “Image”.

Write the component

<figure class="image-block" class:full-width={full_width}>
  {#if image?.url}
    <img src={image.url} alt={alt_text || image.alt || ""} />
  {/if}
  {#if caption}
    <figcaption>{caption}</figcaption>
  {/if}
</figure>

<style>
  .image-block {
    margin: 2rem auto;
    max-width: 1000px;
    padding: 0 2rem;
  }
  
  .image-block.full-width {
    max-width: 100%;
    padding: 0;
  }
  
  .image-block img {
    width: 100%;
    height: auto;
    border-radius: 0.5rem;
  }
  
  .image-block figcaption {
    margin-top: 0.75rem;
    text-align: center;
    color: #666;
    font-style: italic;
    font-size: 0.9rem;
  }
</style>

Add fields

Add these fields:

image (Image) - The image to display (includes URL and alt text)
alt_text (Text, optional) - Override alt text if needed
caption (Text, optional) - Image caption
full_width (Switch/Toggle) - Whether to use full width

Your Image block is complete. It handles images with captions and full-width options.

Block 4: Card Grid

A flexible grid for displaying cards (useful for features, team members, etc.).

Create the Card Grid block

Create a new block called “Card Grid”.

Write the component

<section class="card-grid" style="--columns: {Math.max(1, Number(columns) || 3)}">
  {#each cards ?? [] as card}
    <div class="card">
      {#if card.image?.url}
        <img src={card.image.url} alt={card.image.alt || card.title} />
      {/if}
      <div class="card-content">
        <h3>{card.title}</h3>
        {#if card.description}
          <p>{card.description}</p>
        {/if}
        {#if card.link}
          <a href={card.link} class="card-link">Learn More →</a>
        {/if}
      </div>
    </div>
  {/each}
</section>

<style>
  .card-grid {
    display: grid;
    grid-template-columns: repeat(var(--columns), 1fr);
    gap: 2rem;
    padding: 3rem 2rem;
    max-width: 1200px;
    margin: 0 auto;
  }
  
  .card {
    background: white;
    border-radius: 0.5rem;
    overflow: hidden;
    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    transition: transform 0.2s, box-shadow 0.2s;
  }
  
  .card:hover {
    transform: translateY(-4px);
    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.15);
  }
  
  .card img {
    width: 100%;
    height: 200px;
    object-fit: cover;
  }
  
  .card-content {
    padding: 1.5rem;
  }
  
  .card-content h3 {
    margin-bottom: 0.75rem;
    font-size: 1.5rem;
  }
  
  .card-content p {
    color: #666;
    margin-bottom: 1rem;
  }
  
  .card-link {
    color: #4f46b6;
    text-decoration: none;
    font-weight: 600;
  }
  
  @media (max-width: 768px) {
    .card-grid {
      grid-template-columns: 1fr;
    }
  }
</style>

Add fields

Add these fields:

cards (Repeater) - Array of card objects with:
- title (Text)
- description (Text, optional)
- image (Image, optional)
- link (URL, optional)
columns (Number) - Number of columns (the example code falls back to 3 when empty)

Save the Card Grid block and preview several cards, including one without an image or link.

Primo supplies the page-level <footer> wrapper, so this block uses a <div>. You can copy the block into each page type. Each type keeps its own section content; use Site Field references when values should be shared across types.

Create the Footer block

Create a new block called “Footer”.

Write the component

<div class="footer">
  <div class="footer-content">
    <div class="footer-links">
      {#each links ?? [] as link}
        <a href={link.url}>{link.label}</a>
      {/each}
    </div>
    <p class="copyright">{copyright_text}</p>
  </div>
</div>

<style>
  .footer {
    background: #1a1a1a;
    color: white;
    padding: 3rem 2rem;
    margin-top: 4rem;
  }
  
  .footer-content {
    max-width: 1200px;
    margin: 0 auto;
    text-align: center;
  }
  
  .footer-links {
    display: flex;
    justify-content: center;
    gap: 2rem;
    margin-bottom: 2rem;
    flex-wrap: wrap;
  }
  
  .footer-links a {
    color: white;
    text-decoration: none;
    transition: opacity 0.2s;
  }
  
  .footer-links a:hover {
    opacity: 0.7;
  }
  
  .copyright {
    color: #888;
    font-size: 0.9rem;
  }
</style>

Add fields

Add these fields:

copyright_text (Text) - Copyright notice
links (Repeater) - Footer links with:
- label (Text)
- url (URL)

Save your Footer block. Add it to each page type that needs a footer.

You now have five reusable blocks in your component library. These can be used across all your sites!

Step 3: Define Page Types

Create General Page for the homepage and About page, and Blog Post for articles. The names identify your templates; they do not assign URLs or special behavior.

Page Type 1: General Page

Create General Page

Open Pages → Manage page types → Create page type. Name it “General Page” and choose an icon and color.

Configure available blocks

In the Blocks tab, add Hero, Text, Image, Card Grid, and Footer from the library. This creates independent copies in your site. Enable these blocks for the body slot:

Hero
Text
Image
Card Grid

These blocks will be available for editors to add in the body slot. We’ll add the Footer to the footer slot later.

Add page fields

Add these page-level fields:

meta_title (Text) - SEO title
meta_description (Text) - SEO description

Page Type 2: Blog Post

Create Blog Post page type

Create a new page type called “Blog Post”.

Configure available blocks

Enable the site’s Text and Image blocks for this type:

Text
Image

Blog posts typically have simpler layouts. You can always add more blocks later.

Add page fields

Add these fields:

title (Text) - Post title
author (Text) - Author name
publish_date (Date) - Publication date
featured_image (Image) - Featured image
excerpt (Text) - Short description
meta_title (Text) - SEO title
meta_description (Text) - SEO description

The Date input uses YYYY-MM-DD; resolved values can also include an ISO timestamp. Format it with an explicit UTC time zone to avoid displaying the previous day, for example new Date(publish_date).toLocaleDateString("en-US", { timeZone: "UTC" }). This field does not schedule publication.

Step 4: Create Pages

Now let’s create actual pages using these page types.

Create the Homepage

Open the homepage

Open the homepage created with your blank site. Use “General Page” as its page type. The homepage is the root page at /; creating a normal page named Home does not make it the homepage.

Add blocks

Add blocks in this order:

Hero - Add a headline and call-to-action link
Text - Add an introduction section
Card Grid - Add 3 feature cards
Text - Add a closing section

You can reorder blocks by dragging them in the editor.

Fill in content

Edit each block with your content:

Hero: Welcome message and primary button link
Text: Introduction to your site
Card Grid: Three feature highlights
Text: Call to action or closing message

Set page metadata

Fill in the page fields:

Meta title: “Home - My Site”
Meta description: “Welcome to my site built with Primo”

Create a Blog Post

Create blog post

Create a new page with “Blog Post” page type.

Fill page fields

Set:

Title: “Getting Started with Primo”
Author: Your name
Publish date: Select a date from the date picker
Excerpt: A short description

Add content blocks

Add:

Text block with your blog post content
Image block for illustrations

You can add multiple Text and Image blocks to create rich blog post layouts.

Create the About Page

Create about page

Create a page named About with slug about using the General Page type. It can use the same type as the homepage while having different sections and content.

Build the page

Add:

Hero - “About Us” headline
Text - Your story
Card Grid - Team members or values
Image - Team photo or office image

Add the Footer block to each page type so it appears on every page:

Add Footer to General Page

Open the General Page type editor and add the Footer block to the Footer slot.

Blocks in the footer slot appear on every page of this type and can’t be removed by editors.

Add Footer to other page types

Repeat for the Blog Post type. About already uses General Page, so it gets that type’s shared footer.

Each page type has its own footer section content. Use Site Field references for copyright and links if you want one shared value across page types.

Set the shared footer content

Edit the shared footer section in each page type to add:

Copyright text
Footer links (Privacy Policy, Terms, Contact, etc.)

Use the footer’s links repeater to add links to /, /about, and your blog post’s actual path. To create /blog/getting-started, create a Blog parent page and a child with slug getting-started. Page type names do not add URL prefixes. Give the Hero block’s CTA the URL /about. Open each link in the page preview to verify its destination. The SEO fields you created do not generate tags automatically. In each page type’s Head HTML, add:

<title>{meta_title || "My First Site"}</title>
{#if meta_description}
  <meta name="description" content={meta_description} />
{/if}

The Blog Post’s title, author, and featured_image fields also need Page Field references in a display block to appear on the page. Until you build that header block, include the visible post title and author in the Text section.

Step 7: Publish your site

Use a deployed CMS with a connected hostname. If you built locally, deploy your workspace before following these steps.

Save and review

Save open block, section, and site dialogs. Preview each page and test links, text alignment, image alt text, and mobile layouts.

Publish

Click Publish → Publish changes. This publishes the site, including all its pages. Wait for success, then open your connected domain and confirm the new content and metadata.

What You’ve Built

You now have:

✅ A site structure with two page types
✅ Five reusable blocks in your component library
✅ Multiple published pages with real content
✅ Navigation and footer configured
✅ A site ready for content editors

Next Steps

Writing Components

Learn advanced techniques for building reusable components.

Working with Fields

Explore all field types and how to use them effectively.

Defining Page Types

Master page type configuration for complex content structures.

Using the Editor

Learn how content editors use Primo to manage pages.

All the blocks you created are saved in your component library. You can reuse them in future sites, saving time on every new project.

Getting Started

Building Sites

CLI

Collaboration

Content Management

Dashboard

Reference

Building from Scratch

Watch the workflow

Create a site from a starter

Overview

Download the complete example

Prerequisites

Step 1: Create Your Site

Step 2: Build Your Component Library

Block 1: Hero

Block 2: Text

Block 3: Image

Block 4: Card Grid

Block 5: Footer

Step 3: Define Page Types

Page Type 1: General Page

Page Type 2: Blog Post

Step 4: Create Pages

Create the Homepage

Create a Blog Post

Create the About Page

Step 5: Add Footer to Page Types

Step 6: Connect navigation and page metadata

Step 7: Publish your site

What You’ve Built

Next Steps

Writing Components

Working with Fields

Defining Page Types

Using the Editor

​Watch the workflow

​Create a site from a starter

​Overview

​Download the complete example

​Prerequisites

​Step 1: Create Your Site

​Step 2: Build Your Component Library

​Block 1: Hero

​Block 2: Text

​Block 3: Image

​Block 4: Card Grid

​Block 5: Footer

​Step 3: Define Page Types

​Page Type 1: General Page

​Page Type 2: Blog Post

​Step 4: Create Pages

​Create the Homepage

​Create a Blog Post

​Create the About Page

​Step 5: Add Footer to Page Types

​Step 6: Connect navigation and page metadata

​Step 7: Publish your site

​What You’ve Built

​Next Steps

Writing Components

Working with Fields

Defining Page Types

Using the Editor

Watch the workflow

Create a site from a starter

Overview

Download the complete example

Prerequisites

Step 1: Create Your Site

Step 2: Build Your Component Library

Block 1: Hero

Block 2: Text

Block 3: Image

Block 4: Card Grid

Block 5: Footer

Step 3: Define Page Types

Page Type 1: General Page

Page Type 2: Blog Post

Step 4: Create Pages

Create the Homepage

Create a Blog Post

Create the About Page

Step 5: Add Footer to Page Types

Step 6: Connect navigation and page metadata

Step 7: Publish your site

What You’ve Built

Next Steps