Cheatsheet

# Build site
bengal build                           # Full build
bengal build --fast                    # Parallel + quiet output
bengal build --incremental             # Only changed files
PYTHON_GIL=0 bengal build --fast       # Maximum speed (Python 3.14+)

# Development server
bengal serve                           # Default port 5173
bengal serve --port 8080               # Custom port
bengal serve --no-open                 # Don't open browser

# Clean
bengal clean                           # Remove output directory
bengal clean --cache                   # Also clear build cache

# New project
bengal new site mysite                 # Interactive wizard
bengal new site mysite --init-preset blog   # Skip wizard

# New content
bengal new page my-page                # Page at content/my-page.md
bengal new page post --section blog    # Page at content/blog/post.md

# New templates
bengal new layout article              # templates/article/single.html
bengal new partial sidebar             # templates/partials/sidebar.html
bengal new theme mytheme               # themes/mytheme/

bengal validate                        # Full validation
bengal validate --strict               # Fail on warnings (for CI)
bengal validate --changed              # Only changed files
bengal health linkcheck                # Check all links

bengal config show                     # Show effective config
bengal config doctor                   # Diagnose issues
bengal config diff                     # Compare environments
bengal config init                     # Create config directory

bengal utils theme list                # List available themes
bengal utils theme debug               # Debug theme resolution
bengal utils perf                      # Performance metrics
bengal utils graph analyze             # Site structure analysis
bengal utils graph suggest             # Link suggestions

---
title: "Page Title"                    # Required
description: "SEO meta description"    # Recommended
date: 2024-01-15                       # Publication date
draft: false                           # true = exclude from production
weight: 10                             # Sort order (lower = first)
---

---
tags: [python, tutorial, beginner]
categories: [guides]
author: "Jane Doe"
---

---
type: post                             # Template type (templates/post/)
layout: custom                         # Override default layout
template: special.html                 # Specific template file
---

---
aliases: ["/old-url/", "/another/"]    # URL redirects
slug: custom-url                       # Override URL slug
url: /exact/path/                      # Exact URL path
cascade:                               # Pass to child pages
  author: "Jane Doe"
  draft: true
outputs: [html, json, rss]             # Output formats
no_format: true                        # Skip HTML formatting
---

{{ page.title }}              {# Page title #}
{{ page.description }}        {# Meta description #}
{{ page.content }}            {# Rendered HTML content #}
{{ page.summary }}            {# Auto-generated excerpt #}
{{ page.url }}                {# Page URL path #}
{{ page.permalink }}          {# Full URL with baseurl #}
{{ page.date }}               {# Publication date #}
{{ page.lastmod }}            {# Last modified date #}
{{ page.draft }}              {# Draft status (boolean) #}
{{ page.weight }}             {# Sort weight #}
{{ page.tags }}               {# List of tags #}
{{ page.categories }}         {# List of categories #}
{{ page.reading_time }}       {# Estimated reading time #}
{{ page.word_count }}         {# Word count #}
{{ page.toc }}                {# Table of contents HTML #}

{{ site.title }}              {# Site title #}
{{ site.description }}        {# Site description #}
{{ site.baseurl }}            {# Base URL #}
{{ site.language }}           {# Site language code #}
{{ site.author }}             {# Default author #}
{{ site.pages }}              {# All pages #}
{{ site.sections }}           {# All sections #}
{{ site.menus.main }}         {# Main menu items #}

{{ section.title }}           {# Section title #}
{{ section.pages }}           {# Pages in this section #}
{{ section.subsections }}     {# Child sections #}
{{ section.parent }}          {# Parent section #}

{% for page in section.pages | sort(attribute='date', reverse=true) %}
  <article>
    <h2><a href="{{ page.url }}">{{ page.title }}</a></h2>
    <time>{{ page.date | date('%B %d, %Y') }}</time>
    <p>{{ page.summary }}</p>
  </article>
{% endfor %}

{% for tag in page.tags %}
  <a href="/tags/{{ tag | slugify }}/" class="tag">{{ tag }}</a>
{% endfor %}

{% if page.draft %}
  <div class="draft-banner">⚠️ Draft</div>
{% endif %}

{% if page.toc %}
  <nav class="toc">{{ page.toc }}</nav>
{% endif %}

{% include "partials/header.html" %}
{% include "partials/footer.html" %}
{% include "partials/sidebar.html" with context %}

<nav>
  {% for item in site.menus.main | sort(attribute='weight') %}
    <a href="{{ item.url }}"
       {% if page.url == item.url %}class="active"{% endif %}>
      {{ item.name }}
    </a>
  {% endfor %}
</nav>

<nav class="breadcrumbs">
  <a href="/">Home</a>
  {% for ancestor in page.ancestors %}
    <span>/</span>
    <a href="{{ ancestor.url }}">{{ ancestor.title }}</a>
  {% endfor %}
  <span>/</span>
  <span>{{ page.title }}</span>
</nav>

mysite/
├── bengal.toml              # Configuration
├── content/                 # Source content
│   ├── _index.md            # Homepage
│   ├── about.md             # Standalone page
│   └── blog/                # Section
│       ├── _index.md        # Section index
│       ├── first-post.md    # Blog post
│       └── second-post/     # Page bundle
│           ├── index.md     # Page content
│           └── image.png    # Co-located asset
├── templates/               # Custom templates
│   ├── base.html            # Base template
│   ├── partials/            # Reusable fragments
│   └── post/                # Post type templates
│       └── single.html
├── assets/                  # Static assets
│   ├── css/
│   ├── js/
│   └── images/
├── data/                    # Data files (YAML/JSON)
├── themes/                  # Local themes
└── public/                  # Output (generated)

[site]
title = "My Site"
baseurl = "https://example.com"

[site]
title = "My Site"
baseurl = "https://example.com"
description = "Site description for SEO"
language = "en"
author = "Your Name"

[build]
output_dir = "public"
fast_mode = true                # Parallel + quiet
incremental = true              # Default: true

[theme]
name = "default"
default_appearance = "system"   # light, dark, system

[assets]
minify = true
fingerprint = true

[markdown]
parser = "mistune"
table_of_contents = true
gfm = true

[[menu.main]]
name = "Home"
url = "/"
weight = 1

[[menu.main]]
name = "Blog"
url = "/blog/"
weight = 2

{{ "hello world" | title }}           {# Hello World #}
{{ "Hello World" | slugify }}         {# hello-world #}
{{ page.date | date('%Y-%m-%d') }}    {# 2024-01-15 #}
{{ page.date | timeago }}             {# 2 days ago #}
{{ text | truncate(100) }}            {# First 100 chars... #}
{{ text | striptags }}                {# Remove HTML tags #}
{{ list | length }}                   {# Count items #}
{{ list | first }}                    {# First item #}
{{ list | last }}                     {# Last item #}
{{ list | sort(attribute='date') }}   {# Sort by attribute #}
{{ list | reverse }}                  {# Reverse order #}
{{ list | join(', ') }}               {# Join with comma #}
{{ path | asset_url }}                {# Fingerprinted URL #}