Showing Posts From
Quickstart
Getting Started with Bookworm Light
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 filesStep 1: Create Your Project Structure Start by creating a new directory for your project: mkdir my-bookworm-site cd my-bookworm-site mkdir pagesYour project will have this structure: my-bookworm-site/ site.json # Site configuration pages/ # Content files home.json about.json first-post.jsonStep 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 OptionsField Purposename Your site title (appears in header, SEO)navigation Defines your menu structuredesignTokens Customizes colors and typographytheme Must be bookworm-lightStep 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-siteThe build process will:Read your site.json configuration Process all pages in the pages/ directory Generate author profile pages Create category and tag archive pages Output a static site ready for deploymentStep 7: Preview Locally Start a local development server: npm run devOpen 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:Multi-Author Publishing Guide - Learn collaborative workflows Category System - Organize your content effectively Design Tokens Guide - Customize every visual aspect Technical Architecture - Understand how it all worksHappy publishing!