Key Concepts

Pagesmith generates Astro projects. This guide explains the rendering and deployment terms you may see in the editor and project files.

Rendering Strategies: SSG vs SSR vs CSR

Rendering affects how a browser and crawler receive page content. It is one part of performance and technical SEO, but it does not determine either outcome by itself.

Static Site Generation (SSG)

What it is: Pages are built into HTML files before a visitor requests them.

Pagesmith default: Most pages use SSG.

Build time:  Markdown/Components → HTML files
User visit:  Host returns the built HTML file

Benefits:

• No server rendering step for each request
• Main content can be present in the HTML response
• Static files are straightforward to cache and host
• Works without JavaScript

Common uses: Landing pages, blogs, documentation, and marketing sites.

Server-Side Rendering (SSR)

What it is: Pages are generated on each request by a server.

Pagesmith option: Add SSR when you need dynamic content.

User visit:  Request → Server generates HTML → Response

Benefits:

• Fresh data on every request
• Can access databases and APIs
• Content personalization possible

Common uses: User dashboards, authenticated content, and request-specific data.

Client-Side Rendering (CSR)

What it is: JavaScript in the browser renders some or all of the page content.

An Astro project can include client-rendered components when they are useful. Pagesmith uses static generation or server rendering for page output where possible.

User visit:  HTML response → Download JS → Execute → Render client content

Tradeoffs:

• More JavaScript can increase loading and processing work
• Important content may depend on successful JavaScript execution
• Search engines can render JavaScript, but rendering adds another step and can fail

Astro: The Framework Behind Pagesmith

Pagesmith generates Astro projects. Astro supports static output, server rendering, and interactive components within otherwise static pages.

Why Astro?

1. Server-first output: Astro components do not add browser JavaScript unless a component is hydrated.
2. UI framework support: A project can use React and other supported frameworks for interactive components.
3. Islands architecture: Only selected components need to run in the browser.
4. Build tools: Astro provides routing, asset handling, and build configuration.

Astro Project Structure

my-site/
├── src/
│   ├── pages/           # Routes (each file = a page)
│   │   ├── index.astro  # → yoursite.com/
│   │   ├── about.astro  # → yoursite.com/about
│   │   └── blog/
│   │       └── [slug].astro  # → Dynamic blog posts
│   ├── components/      # Reusable UI pieces
│   ├── layouts/         # Page templates
│   └── content/         # Markdown/MDX content
├── public/              # Static assets (images, fonts)
└── astro.config.mjs     # Configuration

Islands Architecture

Islands let you add interactivity to specific parts of a static page without hydrating the entire page with JavaScript.

How Islands Work

┌─────────────────────────────────────────┐
│  Static HTML (no JS)                    │
│  ┌─────────────┐                        │
│  │ React Island│ ← Interactive component│
│  │ (with JS)   │   hydrates independently│
│  └─────────────┘                        │
│  More static HTML (no JS)               │
│  ┌─────────────┐                        │
│  │ React Island│ ← Another island       │
│  └─────────────┘                        │
└─────────────────────────────────────────┘

Example: Contact Form Island

Most of your landing page is static. Only the contact form needs JavaScript:

---
// Static page content
import ContactForm from '../components/ContactForm.jsx';
---

<h1>Contact Us</h1>
<p>We'd love to hear from you.</p>

<!-- This React component hydrates on page load -->
<ContactForm client:load />

The browser receives the page HTML first. The form becomes interactive after its JavaScript loads and runs.

Island Directives

Astro provides different loading strategies:

Edge Deployment

Pagesmith deploys sites to Cloudflare’s global edge network.

What is Edge Deployment?

Pagesmith hosting uses Cloudflare’s network. Cloudflare chooses how to route each request based on its infrastructure and the deployed project.

Request → Cloudflare network → Deployed site

Benefits

• Static assets can be cached near visitors
• TLS and request routing are handled by the hosting platform
• Server-rendered pages can run close to the network edge
• Actual response time depends on the visitor, page, integrations, and cache state

Database: Cloudflare D1

When you need dynamic data, Pagesmith can add a SQLite database via Cloudflare D1.

How It Works

SSR Page Request
       ↓
Cloudflare Worker (Edge)
       ↓
D1 Database Query
       ↓
Generated HTML Response

Use Cases

• User-generated content
• Dynamic listings
• Simple authentication
• Form submissions storage

See Database for implementation details.

SEO Fundamentals

Pagesmith provides fields and generated files for common technical SEO tasks. You still need accurate content, useful internal links, and a review of the published site.

What Pagesmith Generates

For every page:

<head>
  <title>Page Title | Site Name</title>
  <meta name="description" content="Page description...">
  <link rel="canonical" href="https://yoursite.com/page">

  <!-- Open Graph (Facebook, LinkedIn) -->
  <meta property="og:title" content="Page Title">
  <meta property="og:description" content="...">
  <meta property="og:image" content="/og-image.png">

  <!-- Twitter Card -->
  <meta name="twitter:card" content="summary_large_image">
</head>

Plus site-wide:

• sitemap.xml: URLs you want search engines to discover
• robots.txt: Crawler access instructions

Why This Matters

Search engines use HTML, links, resources, and other signals to understand a page. With static output, the main content can be present in the first response:

1. Crawler visits your page
2. Receives the generated HTML
3. Decides whether to render, index, and rank the page

With client-rendered content:

1. Crawler visits your page
2. Receives an HTML response and JavaScript
3. Renders the JavaScript when its systems support it
4. Decides whether to index the resulting content

Concept Reference

Check the generated project when rendering behavior matters. A form, authenticated page, or third-party script may require different settings from a static content page.