Getting Started with Bookworm Light

This guide will walk you through setting up your first site using the Bookworm Light theme adapter. By the end of this tutorial, you’ll have a fully functional blog with multi-author support, category organization, and custom branding.

Prerequisites

Before you begin, ensure you have:

• Node.js 18 or later installed
• npm or yarn package manager
• A text editor (VS Code recommended)
• Basic familiarity with JSON configuration files

Step 1: Create Your Project Structure

Start by creating a new directory for your project:

mkdir my-bookworm-site
cd my-bookworm-site
mkdir pages

Your project will have this structure:

my-bookworm-site/
  site.json       # Site configuration
  pages/          # Content files
    home.json
    about.json
    first-post.json

Step 2: Configure site.json

Create your site configuration file. This is the heart of your site’s identity:

{
  "id": "my-site-id",
  "name": "My Awesome Blog",
  "domain": "myblog.example.com",
  "baseUrl": "/",
  "theme": "bookworm-light",
  "defaultTemplate": "article",
  "navigation": [
    { "label": "Home", "url": "/" },
    { "label": "Authors", "url": "/authors" },
    { "label": "Categories", "url": "/categories" },
    { "label": "About", "url": "/about" }
  ],
  "designTokens": {
    "colors": {
      "brand": {
        "primary": "#3b82f6",
        "secondary": "#1d4ed8",
        "accent": "#f59e0b"
      }
    }
  }
}

Key Configuration Options

Field	Purpose
name	Your site title (appears in header, SEO)
navigation	Defines your menu structure
designTokens	Customizes colors and typography
theme	Must be bookworm-light

Step 3: Create Your First Page

Create pages/home.json for your homepage:

{
  "id": "home",
  "site": "my-site-id",
  "url": "/",
  "title": "Welcome to My Blog",
  "description": "A personal blog about technology and creativity.",
  "template": "article",
  "metadata": {
    "authors": ["your-name"],
    "date": "2026-08-05",
    "categories": ["announcements"],
    "tags": ["welcome", "introduction"]
  },
  "content": {
    "type": "inline",
    "content": "# Welcome!\n\nThis is my first blog post..."
  }
}

Step 4: Define Your Authors

Add author profiles to your site.json:

{
  "authors": [
    {
      "id": "your-name",
      "name": "Your Name",
      "title": "Founder & Writer",
      "image": "/images/authors/your-name.jpg",
      "bio": "I write about technology, creativity, and building things.",
      "social": {
        "twitter": "https://twitter.com/yourhandle",
        "github": "https://github.com/yourhandle"
      }
    }
  ]
}

Step 5: Add Design Customization

Customize your site’s appearance with design tokens:

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

Step 6: Build Your Site

Run the platform’s build command to generate your site:

npm run build -- --project ./my-bookworm-site

The build process will:

1. Read your site.json configuration
2. Process all pages in the pages/ directory
3. Generate author profile pages
4. Create category and tag archive pages
5. Output a static site ready for deployment

Step 7: Preview Locally

Start a local development server:

npm run dev

Open http://localhost:4321 to see your site.

Common Configuration Patterns

Adding Navigation Dropdowns

{
  "navigation": [
    { "label": "Home", "url": "/" },
    {
      "label": "Topics",
      "children": [
        { "label": "Technology", "url": "/categories/technology" },
        { "label": "Design", "url": "/categories/design" },
        { "label": "Business", "url": "/categories/business" }
      ]
    },
    { "label": "About", "url": "/about" }
  ]
}

Multiple Authors per Post

{
  "metadata": {
    "authors": ["alice-smith", "bob-johnson", "carol-williams"]
  }
}

Full SEO Configuration

{
  "seo": {
    "title": "Custom Page Title for Search Engines",
    "description": "A detailed description for search results.",
    "openGraph": {
      "title": "Title for Social Sharing",
      "description": "Description when shared on social media.",
      "image": "/images/social-preview.jpg",
      "type": "article"
    },
    "twitter": {
      "card": "summary_large_image"
    },
    "canonical": "https://myblog.example.com/my-post"
  }
}

Troubleshooting

Navigation Not Updating

Ensure your site.json navigation array exactly matches the pages you want to display. The adapter uses ONLY this array - no theme defaults.

Author Pages Empty

Verify that author slugs in your pages match the author IDs in site.authors[].

Styles Not Applying

Check that your designTokens follow the correct structure. The adapter maps these to theme.json.

Next Steps

Now that you have a working site, explore:

1. Multi-Author Publishing Guide - Learn collaborative workflows
2. Category System - Organize your content effectively
3. Design Tokens Guide - Customize every visual aspect
4. Technical Architecture - Understand how it all works

Happy publishing!