Installation Guide

This guide will help you install and set up Quesby, a privacy-first static site boilerplate built with Eleventy and Decap CMS.

Quick Start

For experienced developers who want to get started immediately:

# 1. Clone and install
git clone https://github.com/quesby/quesby-boilerplate.git your-project
cd your-project
pnpm install

# 2. Start development
pnpm serve

# 3. Open browser
open http://localhost:8080

# 4. Create your first blog post
npx quesby new post "Welcome to Quesby"

New to static sites? Follow the detailed guide below for step-by-step instructions.

Prerequisites

Before installing Quesby, ensure you have the following installed on your system:

• Node.js (version 18 or higher)
• pnpm (recommended) or npm (comes with Node.js)
• Git (for version control)

Package Manager Options

Quesby supports multiple package managers. Choose the one that best fits your workflow:

Using Corepack (Recommended)

Corepack is the easiest way to manage package managers automatically:

# Enable corepack (comes with Node.js 16.10+)
corepack enable

# The project will automatically use pnpm based on package.json configuration

Manual Installation

If you prefer to install pnpm manually:

# Install pnpm globally
npm install -g pnpm

# Or using corepack
corepack prepare pnpm@latest --activate

Checking Prerequisites

Verify your installations:

node --version
pnpm --version  # or npm --version
git --version

Installation Methods

Choose the method that best fits your workflow:

Method 1: Clone from Repository (Recommended)

Best for: Developers, contributors, and anyone who wants to stay updated

1. Clone the repository:

   git clone https://github.com/quesby/quesby-boilerplate.git
   cd quesby-boilerplate

2. Install dependencies:

   pnpm install    # Recommended: fast and efficient
   # npm install   # Alternative: standard Node.js
   # yarn install  # Alternative: yarn projects

Note: All examples in this guide show pnpm commands. Replace pnpm with npm or yarn if using a different package manager.

3. Set up your own Git repository (optional)

   # Remove the original remote
   git remote remove origin
   
   # Add your own repository
   git remote add origin https://github.com/your-user/your-repo.git
   
   # Push the initial commit
   git push -u origin main

Method 2: Download and Extract

Best for: Quick setup, production deployments, or when you don't need git history

1. Download the latest release from the GitHub repository
2. Extract the archive to your desired location
3. Navigate to the project directory
4. Run pnpm install (or npm install / yarn install)

Environment Configuration

Setting Up Content Directory

Quesby supports external content management through multiple configuration methods:

Configuration Priority

The system checks configurations in this order (first found wins):

1. Environment variable (.env file) - Highest priority
2. site.json configuration - Fallback
3. Default (src/content) - If neither is set

Method 1: Environment Variable (Recommended)

1. Create a .env file in the project root:

   touch .env

2. Configure the content path:

   QUESBY_CONTENT_PATH=/path/to/your/content/directory

Method 2: site.json Configuration

Edit src/_data/site.json:

{
  "contentPath": "/absolute/path/to/your/content"
}

Tip: Environment variables are ideal when working across different machines or environments (dev/staging/prod), while site.json defines project-wide defaults.

Theme Configuration

Quesby comes with built-in themes and supports custom themes:

Built-in Themes

Setting the Theme

Configuration in src/_data/site.json

{
  "theme": "quesby-core"
}

Creating Custom Themes

1. Copy an existing theme:

   cp -r src/themes/quesby-core src/themes/my-custom-theme

2. Modify theme files in src/themes/my-custom-theme/

3. Set your theme:

{
  "theme": "my-custom-theme"
}

Learn more: See Theme Development Guide for detailed customization instructions.

Development Setup

1. Start Development Server

Run the development server with CSS watching:

pnpm serve

This command will:

• Start Eleventy in serve mode
• Watch for CSS changes and recompile automatically
• Serve your site at http://localhost:8080

2. Alternative Development Commands

• Development without CSS watching:

  pnpm dev

• CSS-only watching:

  pnpm css:watch

• Build CSS only:

  pnpm css:build

Building for Production

Build the Site

Generate the production build:

pnpm build

This will:

• Compile all SCSS to CSS
• Process all templates and content
• Generate the static site in the _site directory

Build Output

The built site will be available in the _site directory, ready for deployment to any static hosting service.

Content Management

Using Decap CMS

1. Access the admin panel: Navigate to http://localhost:8080/admin in your browser

2. Configure authentication: Follow the Decap CMS documentation to set up authentication for your chosen backend

3. Content structure:

   Quesby automatically creates collections based on your content structure:

   Collection	Directory	Required	Description
   Posts	src/content/posts/	✅ Yes	Blog articles and news
   Documentation	src/content/documentation/	✅ Yes	Help and guides
   Pages	src/content/pages/	❌ Optional	Static pages (About, Contact)
   Projects	src/content/projects/	❌ Optional	Portfolio showcases
   News	src/content/news/	❌ Optional	News articles

   Note: Only posts and documentation are required. Other collections are optional and can be added as needed.

Manual Content Management

You can also manage content manually by editing Markdown files in the appropriate directories.

Troubleshooting

Common Issues

1. Content Directory Not Found

Error: ❌ Content path not found

Solutions:

# Check your configuration
cat .env | grep QUESBY_CONTENT_PATH
cat src/_data/site.json | grep contentPath

# Verify directory exists
ls -la /path/to/your/content/directory

2. CSS Not Compiling

Error: Styles not updating or SCSS errors

Solutions:

# Check SCSS syntax
pnpm css:build

# Verify theme exists
ls -la src/themes/

# Restart CSS watcher
pnpm css:watch

3. Port Already in Use

Error: Port 8080 is already in use

Solutions:

• Eleventy automatically finds an available port
• Check terminal output for the actual URL
• Or specify a different port: pnpm dev --port 3000

4. Package Manager Issues

Error: Command not found (pnpm/npm/yarn)

Solutions:

# Enable corepack
corepack enable

# Or install manually
npm install -g pnpm

Getting Help

• Documentation: Troubleshooting Guide | Configuration Guide
• GitHub Issues: Report bugs or request features
• Discussions: Community support
• Quick Fixes: Check the Common Issues section below

Next Steps

After successful installation, here's what to do next:

Immediate Actions

1. Verify installation: Check that http://localhost:8080 loads correctly
2. Create your first post: Use the CLI tool to create a new blog post

   npx quesby new post "My First Post"

3. Explore the admin: Visit http://localhost:8080/admin to see the CMS
4. Check content: Browse the sample posts and documentation

Learning Path

1. Configuration Guide - Customize your site settings
2. Theme System - Customize appearance and create themes
3. Content Management - Learn to manage content
4. Development Guide - Advanced customization
5. Deployment Guide - Publish your site

Quick Wins

• Change site name: Edit src/_data/site.json
• Add your content: Create posts in src/content/posts/
• Customize theme: Modify files in src/themes/quesby-core/
• Set up CMS: Configure authentication in src/admin/config.yml

System Requirements

Minimum Requirements

• Node.js: 18.0.0 or higher (includes corepack)
• Package Manager: pnpm (recommended), npm, or yarn
• Memory: 512MB RAM minimum
• Disk Space: 100MB for the project, additional space for content

Recommended Setup

• Node.js: 20.0.0 or higher (latest LTS)
• Package Manager: pnpm with corepack
• Memory: 1GB RAM or more
• Disk Space: 500MB+ for development with dependencies

Corepack Requirements

• Node.js: 16.10.0 or higher (corepack included)
• Corepack: Automatically manages package managers
• No additional installation required for pnpm, npm, or yarn

Key Dependencies

Quesby uses modern, well-maintained dependencies:

Note: @quesby/core is automatically installed when you run pnpm install (or npm install / yarn install). It provides the core Eleventy configuration, filters, collections, and SCSS utilities used throughout the boilerplate.

Supported Platforms

Corepack Support

Corepack is supported on all platforms where Node.js 16.10+ is available:

• Windows: Full support with PowerShell and Command Prompt
• macOS: Full support with Terminal and iTerm2
• Linux: Full support with bash, zsh, and other shells