Zero to Deployed

Install Bengal

Requirements

Bengal requires Python 3.14 or later. For best performance, use the free-threaded build (Python 3.14t), which enables true parallel processing.

Install

uv pip install bengal

uvx bengal --version

pip install bengal

pipx install bengal

git clone https://github.com/lbliii/bengal.git
cd bengal
make setup
make install

Verify Installation

bengal --version

You should see output like: Bengal SSG, version 0.1.10

Upgrade Bengal

Bengal includes a built-in upgrade command that automatically detects how it was installed:

# Interactive upgrade (recommended)
bengal upgrade

# Skip confirmation
bengal upgrade -y

# Preview changes without executing
bengal upgrade --dry-run

The upgrade command:

• Detects your installer (uv, pip, pipx, conda)
• Checks PyPI for the latest version (cached for 24 hours)
• Shows a confirmation before making changes

Python Version Setup

# macOS (with Homebrew)
brew install pyenv

# Install Python 3.14
pyenv install 3.14.0

# Set as default
pyenv global 3.14.0

# Verify
python --version

Free-Threaded Python

For best build performance, use the free-threaded Python build (Python 3.14t). This enables true parallel processing for 1.5-2x faster builds on multi-core machines.

# With pyenv
pyenv install 3.14.0t
pyenv global 3.14.0t

# Verify free-threading is enabled
python -c "import sys; print('Free-threaded!' if sys._is_gil_enabled() == False else 'GIL enabled')"

Bengal automatically detects the free-threaded build and enables parallel processing.

Troubleshooting

source .venv/bin/activate

pip uninstall bengal && pip install bengal

python --version
# or
python3 --version

pip install --user bengal

python -m venv venv && source venv/bin/activate
pip install bengal

Next Steps

• Writer Quickstart — Start creating content
• Themer Quickstart — Customize your site's look
• Tutorials — Guided learning journeys

Writer Quickstart

Create your first Bengal site and publish content in 5 minutes. No theming or code required.

Prerequisites

Create Your Site

bengal new site myblog --template blog
cd myblog

The --template blog flag scaffolds a complete blog structure with sample posts. Other templates: default, docs, portfolio, product, resume.

name: My Blog
structure:
  - path: index.md
    type: blog
    props:
      title: My Blog
    content: |
      # Welcome to My Blog

  - path: posts/hello-world.md
    type: blog
    props:
      title: Hello World
      date: "2026-01-15"
    content: |
      # Hello World
      My first post!

bengal project skeleton apply my-blog.yaml

Start the Dev Server

bengal serve

Your browser opens automatically at http://localhost:5173/. The server rebuilds on save—CSS changes apply instantly without page refresh.

Create Your First Post

bengal new page my-first-post --section blog

This creates content/blog/my-first-post.md. Edit it:

---
title: My First Post
date: 2026-01-15
tags: [welcome]
description: Getting started with Bengal
---

# My First Post

Welcome to my blog! Bengal makes publishing simple.

## What's Next

- Add more posts with `bengal new page`
- Customize your theme
- Deploy to the web

Save. The page appears instantly in your browser.

Customize Your Site

Editconfig/_default/site.yaml:

site:
  title: "My Awesome Blog"
  description: "Thoughts on code, design, and life"
  language: "en"

Build and Deploy

bengal build

Output goes to public/. Deploy to any static host:

Bengal auto-detects Netlify, Vercel, and GitHub Pages to setbaseurlautomatically. See Deployment Guide for CI/CD workflows.

Frontmatter Essentials

Every page starts with YAML frontmatter:

---
title: Page Title           # Required
date: 2026-01-15            # Publication date (ISO format)
description: SEO text       # Search/social preview
tags: [tag1, tag2]          # Taxonomy
draft: true                 # Exclude from production
---

Next Steps

• Content Authoring — Markdown features and syntax
• Content Organization — Structure your site
• Theming — Customize appearance
• Build a Blog — Complete tutorial

Deploy Your Site

Bengal generates static HTML, CSS, and JavaScript files. This means you can host your site anywhere that serves static files (e.g., GitHub Pages, Netlify, Vercel, AWS S3, Nginx).

The Production Build

When you are ready to ship, run the build command:

bengal build --environment production

This command:

• Loads configuration fromconfig/environments/production.yaml(if it exists)
• Minifies HTML output (enabled by default)
• Generates thepublic/directory with your complete site

Common Build Flags

Example full command for CI:

bengal build --environment production --strict --clean-output

GitHub Pages

Deploy using GitHub Actions. Create.github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'

      - name: Install Bengal
        run: pip install bengal

      - name: Build Site
        run: bengal build --environment production --strict --clean-output

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './public'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Netlify

Create anetlify.tomlin your repository root:

[build]
  publish = "public"
  command = "bengal build --environment production"

[build.environment]
  PYTHON_VERSION = "3.14"

Vercel

Configure your project:

1. Build Command:bengal build --environment production
2. Output Directory:public
3. Ensure yourrequirements.txt includes bengal.

Automatic Platform Detection

Bengal auto-detects your deployment platform and configuresbaseurlautomatically:

You can override auto-detection with theBENGAL_BASEURLenvironment variable:

BENGAL_BASEURL="https://custom-domain.com" bengal build --environment production

Pre-Deployment Checklist

Before you merge to main or deploy:

1. Runbengal config doctor: Checks for common configuration issues.
2. Runbengal build --strictlocally: Ensures no template errors.
3. Runbengal validate: Runs health checks on your site content.
4. Checkconfig/environments/production.yaml: Ensure your baseurlis set to your production domain.

# config/environments/production.yaml
site:
  baseurl: "https://example.com"