Skip to main content
Documentation

Quick Start Guide

Get up and running with PageJSON in under 5 minutes

Installation

PageJSON requires Node.js 16+ and npm. Install dependencies and start the development server:

Install and Run

bash 
# Clone or download PageJSON
git clone https://github.com/your-org/pagejson.git
cd pagejson

# Install dependencies
npm install

# Start development server (http://localhost:3000)
npm run dev

# Build for production
npm run build

Your First Page

Pages are defined as JSON files in src/data/pages/. Let's create a simple landing page:

Example 1: Simple Landing Page

A minimal landing page with a hero section and CTA

{
  "seo": {
    "title": "Welcome | My Site",
    "description": "My awesome landing page built with PageJSON",
    "canonical": "https://mysite.com/landing"
  },
  "sections": [
    {
      "component": "hero",
      "variant": "simple",
      "data": {
        "heading": "Welcome to My Site",
        "subheading": "Build amazing websites with JSON",
        "buttons": [
          { "text": "Get Started", "url": "/contact", "style": "primary" }
        ],
        "bg": "dark",
        "align": "center"
      }
    },
    {
      "component": "cta",
      "variant": "simple",
      "data": {
        "heading": "Ready to Start?",
        "body": "Contact us today to learn more",
        "buttons": [
          { "text": "Contact Us", "url": "/contact", "style": "primary" }
        ],
        "bg": "light"
      }
    }
  ]
}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Welcome | My Site</title>
  <meta name="description" content="My awesome landing page">
  <link rel="canonical" href="https://mysite.com/landing">
  <!-- Styles loaded -->
</head>
<body>
  <!-- Header -->
  <main>
    <section class="bg-dark text-white py-5">
      <div class="container text-center">
        <h1 class="display-4 mb-3">Welcome to My Site</h1>
        <p class="lead mb-4">Build amazing websites with JSON</p>
        <a href="/contact" class="btn btn-primary">Get Started</a>
      </div>
    </section>
    <!-- CTA section... -->
  </main>
  <!-- Footer -->
</body>
</html>

Multi-Section Homepage

Build a complete homepage with multiple components:

Example 2: Multi-Section Homepage

A full homepage with hero, features, and CTA

{
  "seo": {
    "title": "Home | My Company",
    "description": "Leading provider of amazing services"
  },
  "sections": [
    {
      "component": "hero",
      "variant": "with-image",
      "data": {
        "heading": "Transform Your Business",
        "subheading": "We provide world-class solutions",
        "image": "/assets/img/hero.jpg",
        "buttons": [
          { "text": "Learn More", "url": "/about", "style": "primary" }
        ]
      }
    },
    {
      "component": "feature-grid",
      "variant": "icon-cards",
      "data": {
        "heading": "Our Services",
        "columns": 3,
        "features": [
          {
            "icon": "fa-cog",
            "heading": "Service One",
            "body": "Description of your first service"
          },
          {
            "icon": "fa-chart-line",
            "heading": "Service Two",
            "body": "Description of your second service"
          },
          {
            "icon": "fa-users",
            "heading": "Service Three",
            "body": "Description of your third service"
          }
        ],
        "bg": "light"
      }
    },
    {
      "component": "cta",
      "variant": "dark-centered",
      "data": {
        "heading": "Ready to Get Started?",
        "body": "Contact us today for a free consultation",
        "buttons": [
          { "text": "Contact Us", "url": "/contact", "style": "primary" }
        ]
      }
    }
  ]
}
<!-- Full page with:
     1. Hero section with image
     2. Three-column feature grid
     3. Dark CTA section
     
     All responsive, SEO-optimized,
     with proper semantic HTML -->

Service Page with Contact Form

Create a service page with details and a contact form:

Example 3: Service Page with Form

Service description with integrated contact form

{
  "seo": {
    "title": "Web Development Services | My Company",
    "description": "Professional web development services"
  },
  "sections": [
    {
      "component": "hero",
      "variant": "simple",
      "data": {
        "heading": "Web Development Services",
        "subheading": "Custom websites built to your exact needs",
        "bg": "light",
        "align": "left"
      }
    },
    {
      "component": "content-block",
      "variant": "text-only",
      "data": {
        "heading": "What We Offer",
        "body": "<p>We specialize in building modern, responsive websites using the latest technologies. Our team has over 10 years of experience delivering high-quality web solutions.</p><ul><li>Custom website development</li><li>Responsive design</li><li>SEO optimization</li><li>Ongoing support</li></ul>",
        "bg": "white"
      }
    },
    {
      "component": "contact-form",
      "variant": "simple",
      "data": {
        "heading": "Get in Touch",
        "subheading": "Tell us about your project",
        "fields": [
          { "name": "name", "type": "text", "label": "Name", "required": true },
          { "name": "email", "type": "email", "label": "Email", "required": true },
          { "name": "message", "type": "textarea", "label": "Message", "rows": 5 }
        ],
        "submitText": "Send Message",
        "bg": "light"
      }
    }
  ]
}

Next Steps

Now that you've created your first pages, explore more:

Troubleshooting

Build Errors

Problem: Error: Cannot find module 'gulp'
Solution: Run npm install to install all dependencies.

Page Not Showing

Problem: Created a JSON file but page doesn't appear
Solution: Make sure the file is in src/data/pages/ and ends with .json. Run npm run build to regenerate.

Styles Not Loading

Problem: Page appears but without styling
Solution: Check that npm run dev completed successfully. Look for SCSS compilation errors in the terminal.

Invalid JSON

Problem: Build fails with JSON parse error
Solution: Validate your JSON at jsonlint.com. Common issues: missing commas, trailing commas, unescaped quotes.

Need Help?

Join our community or check the full documentation

View Documentation GitHub Issues