Getting Started with Astroplate

This comprehensive guide walks you through setting up your first Astroplate blog using our publishing platform. Whether you’re new to static site generators or an experienced developer, you’ll find everything you need to get up and running quickly.

Prerequisites

Before diving in, ensure you have the following:

Required Tools

• Node.js 18+ - The runtime for our build tools
• Git - Version control for your project
• A text editor - VS Code recommended with JSON support
• Terminal access - Command line for running scripts

Platform Access

• A valid user account on our publishing platform
• Access to the deployment scripts
• Basic understanding of JSON syntax

Project Structure Overview

Before we start, let’s understand the structure of an Astroplate project:

your-project/
├── site.json           # Site configuration and design tokens
├── pages/
│   ├── home.json       # Homepage content
│   ├── about.json      # About page
│   └── blog-post.json  # Individual articles
└── assets/
    └── images/         # Your images and media

This simple structure is all you need. The adapter handles everything else.

Step 1: Create Your Site Configuration

The site.json file is the heart of your project. It defines your site’s identity, navigation, and visual design.

Basic Site Configuration

Create a site.json file with this structure:

{
  "id": "unique-site-id",
  "user_id": "your-user-uuid",
  "name": "My Awesome Blog",
  "domain": "myblog.example.com",
  "baseUrl": "/",
  "theme": "astroplate",
  "defaultTemplate": "article"
}

Understanding Each Field

Field	Purpose	Example
id	Unique identifier for your site	"my-blog-2026"
user_id	Your platform user ID	UUID format
name	Display name shown in header/footer	"Tech Insights"
domain	Production domain	"blog.yoursite.com"
baseUrl	URL path prefix	"/" or "/blog"
theme	Theme to use	"astroplate"
defaultTemplate	Default page template	"article"

Adding Navigation

The navigation array controls your site’s menu. This is where the magic of dynamic navigation happens:

{
  "navigation": [
    { "label": "Home", "url": "/" },
    { "label": "Blog", "url": "/blog" },
    {
      "label": "Resources",
      "children": [
        { "label": "Documentation", "url": "/docs" },
        { "label": "API Reference", "url": "/api" }
      ]
    },
    { "label": "About", "url": "/about" },
    { "label": "Contact", "url": "/contact" }
  ]
}

Notice the nested children array - this creates dropdown menus automatically!

Configuring Design Tokens

Design tokens let you customize colors, fonts, and more without touching CSS:

{
  "designTokens": {
    "colors": {
      "brand": {
        "primary": "#3b82f6",
        "secondary": "#2563eb",
        "accent": "#f59e0b"
      },
      "background": {
        "page": "#ffffff",
        "surface": "#f8fafc",
        "muted": "#e2e8f0"
      },
      "text": {
        "primary": "#1e293b",
        "secondary": "#64748b",
        "link": "#3b82f6"
      }
    },
    "typography": {
      "fonts": {
        "heading": "'Poppins', sans-serif",
        "body": "'Inter', sans-serif"
      }
    },
    "themeMode": {
      "default": "system",
      "allowToggle": true
    }
  }
}

Step 2: Create Your First Page

Pages are defined as individual JSON files in the pages/ directory.

Article Page Structure

Create pages/my-first-post.json:

{
  "id": "my-first-post",
  "site": "my-blog",
  "url": "/my-first-post",
  "title": "My First Blog Post",
  "description": "An exciting introduction to my new blog",
  "template": "article",
  "metadata": {
    "author": "Your Name",
    "date": "2026-08-10",
    "categories": ["announcements"],
    "tags": ["first-post", "introduction"]
  },
  "content": {
    "type": "inline",
    "content": "# Hello World!\n\nThis is my first blog post..."
  }
}

Metadata Deep Dive

The metadata object contains important information about your content:

{
  "metadata": {
    "author": "Jane Smith",
    "date": "2026-08-10",
    "categories": ["tutorials", "web-development"],
    "tags": ["html", "css", "javascript", "beginner"],
    "featured": true,
    "draft": false
  }
}

Field	Type	Description
author	string	Author name (single author)
date	ISO date	Publication date
categories	string[]	Content categories
tags	string[]	Content tags for discovery
featured	boolean	Highlight on homepage
draft	boolean	Exclude from production

Adding SEO Metadata

Optimize your content for search engines:

{
  "seo": {
    "title": "Custom SEO Title | My Blog",
    "description": "A compelling meta description for search results",
    "canonical": "https://myblog.com/my-first-post",
    "openGraph": {
      "type": "article",
      "image": "/images/my-post-og.jpg",
      "siteName": "My Blog"
    },
    "twitter": {
      "card": "summary_large_image",
      "title": "My First Post",
      "description": "Check out my first blog post!"
    }
  }
}

Step 3: Writing Content

Content is written in Markdown and embedded in the content field.

Inline Content

For shorter posts, use inline content:

{
  "content": {
    "type": "inline",
    "content": "# My Post\n\nYour markdown here..."
  }
}

Markdown Features

Astroplate supports full GitHub-Flavored Markdown:

• Headings - Use # through ######
• Bold and italic text
• Inline code and code blocks with syntax highlighting
• Tables with alignment
• Task lists with checkboxes
• Blockquotes
• Horizontal rules
• Images and links

Code Blocks with Syntax Highlighting

Astroplate includes Shiki for beautiful code highlighting:

```javascript
const greeting = 'Hello, World!';
console.log(greeting);
```

Supported languages include JavaScript, TypeScript, Python, Go, Rust, and dozens more.

Step 4: Deploy Your Site

With your content ready, it’s time to deploy!

Development Preview

Preview your site locally first:

npx tsx scripts/preview-project.ts --project my-blog

This builds your site and serves it at http://localhost:3000.

Production Deployment

Deploy to Cloudflare Pages:

npx tsx scripts/deploy-project.ts --project my-blog

The script will:

1. Copy the Astroplate theme
2. Generate config files (config.json, menu.json, theme.json)
3. Transform your page JSON to Markdown
4. Build the Astro site
5. Push to GitHub
6. Trigger Cloudflare Pages deployment

Deployment Output

You’ll see output like:

[Astroplate] Generating config files for site: My Awesome Blog
[Astroplate] Generated config.json with site.title="My Awesome Blog"
[Astroplate] Generated menu.json with 4 main menu items
[Astroplate] Generated theme.json with primary color: #3b82f6
[Astroplate] Generated 3 content files
[Build] Build completed in 28.4s
[Deploy] Site deployed to https://myblog.example.com

Step 5: Verify Your Site

After deployment, verify everything works:

Checklist

• Homepage loads with correct title
• Navigation shows only your defined pages
• All articles are accessible
• Design tokens are applied (colors, fonts)
• Dark mode toggle works
• Mobile navigation works
• SEO metadata is correct (check with browser devtools)

Common Issues and Solutions

Navigation Shows Wrong Pages

Problem: Extra pages from the original theme appear in navigation.

Solution: The adapter now completely replaces the theme’s menu.json. Ensure your site.json has a complete navigation array.

Styles Don’t Match Design Tokens

Problem: Colors or fonts don’t reflect your designTokens.

Solution: Check that your designTokens structure is correct. The adapter generates theme.json and CSS from these values.

Content Not Appearing

Problem: Page shows but content is empty.

Solution: Verify your content object has type: "inline" and valid Markdown in the content field.

Next Steps

Congratulations! You’ve deployed your first Astroplate site. Here’s what to explore next:

• Advanced Guide - Deep dive into SEO, design tokens, and performance
• About This Platform - Learn about the technology behind the scenes

---

Need help? The Platform Team is here to assist. Check the documentation or reach out through the support channels.