User Scenarios

Pick the scenario that matches your site type, then follow the steps below.

Prerequisites: Bengal installed (pip install bengal). See Installation if needed.

Blog Author Workflow

Build a personal or team blog with posts, categories, and RSS feeds.

What you'll get: A blog site with date-sorted posts, category organization, RSS feed, and pagination.

1. Scaffold a Blog

bengal new site myblog --template blog
cd myblog

2. Configure Pagination

Editconfig/_default/content.yaml:

content:
  default_type: blog
  sort_pages_by: date
  sort_order: desc

pagination:
  per_page: 10

3. Add Posts

Create posts incontent/posts/ directory. Each post should include a datefield for sorting and RSS feed inclusion:

---
title: "My First Post"
date: 2025-01-15
tags:
  - announcement
  - news
categories:
  - Updates
---

# My First Post

Welcome to my blog!

4. Enable RSS

Inconfig/_default/features.yaml:

features:
  rss: true  # Generates rss.xml (limited to 20 most recent posts)

5. Build and Preview

bengal serve

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

Documentation Site

Build technical documentation with search, versioning, and navigation.

What you'll get: A documentation site with hierarchical navigation, search functionality, and structured content organization.

1. Scaffold Documentation

bengal new site mydocs --template docs
cd mydocs

2. Organize Content

Structure your docs incontent/:

content/
├── _index.md           # Docs landing page
├── getting-started/
│   ├── _index.md
│   ├── installation.md
│   └── quickstart.md
├── guides/
│   ├── _index.md
│   └── advanced.md
└── reference/
    ├── _index.md
    └── api.md

3. Configure Search

Search is enabled by default for the docs template (index.jsonoutput). See Configuration to customize search behavior.

4. Add Navigation

Configure menu inconfig/_default/site.yaml:

menu:
  main:
    items:
      - name: "Getting Started"
        url: "/getting-started/"
        weight: 10
      - name: "Guides"
        url: "/guides/"
        weight: 20
      - name: "Reference"
        url: "/reference/"
        weight: 30

Portfolio Site

Showcase projects with a portfolio layout.

What you'll get: A portfolio site with project pages, featured project highlighting, and tag-based organization.

1. Scaffold Portfolio

bengal new site myportfolio --template portfolio
cd myportfolio

2. Add Projects

Create project pages incontent/projects/:

---
title: "Project Alpha"
date: 2025-03-15
tags:
  - python
  - api
featured: true
image: "/images/project-alpha.png"
---

# Project Alpha

Description of your project.

## Technologies

- Python
- FastAPI
- PostgreSQL

## Links

- [GitHub](https://github.com/example/project-alpha)
- [Demo](https://demo.example.com)

3. Configure Featured Projects

Use thefeatured: truefrontmatter field to highlight projects on the homepage. Templates can filter projects by this field to show featured items prominently.

Mixed Content Site

Combine documentation, blog, and portfolio on a single site.

What you'll get: A multi-purpose site with separate sections for different content types, each with appropriate templates and navigation.

1. Create Site Structure

bengal new site mysite --template default
cd mysite

2. Organize by Section

Create sections with cascade for content types:

content/
├── _index.md           # Landing page
├── docs/
│   ├── _index.md       # cascade: type: doc
│   └── guide.md
├── blog/
│   ├── _index.md       # cascade: type: blog
│   └── post-1.md
└── projects/
    ├── _index.md       # cascade: type: portfolio
    └── project-a.md

3. Use Cascade for Content Types

Incontent/docs/_index.md:

---
title: "Documentation"
cascade:
  type: doc
---

In content/blog/_index.md:

---
title: "Blog"
cascade:
  type: blog
---

4. Configure Menu

menu:
  main:
    items:
      - name: "Docs"
        url: "/docs/"
        weight: 10
      - name: "Blog"
        url: "/blog/"
        weight: 20
      - name: "Projects"
        url: "/projects/"
        weight: 30

Multi-Variant Documentation

Build separate doc sites (OSS vs Enterprise, brand1 vs brand2) from one content tree. Common when you acquire a product or maintain paid vs free tiers.

What you'll get: One content repo, multiple deployed sites with edition-specific pages filtered per build.

1. Add Edition to Pages

Mark edition-specific pages in frontmatter:

---
# content/enterprise/sso.md
title: "SSO Configuration"
edition: [enterprise]
---

# SSO Configuration

Configure single sign-on for your organization.

---
# content/oss/contributing.md
title: "Contributing"
edition: [oss]
---

# Contributing

How to contribute to the open-source project.

Pages without editionare included in all builds.

2. Create Environment Configs

config/environments/oss.yaml:

params:
  edition: oss

site:
  baseurl: "https://docs.example.com"

config/environments/enterprise.yaml:

params:
  edition: enterprise

site:
  baseurl: "https://enterprise.example.com"

3. Build Each Variant

bengal build --environment oss
bengal build --environment enterprise

4. Deploy

Deploy each build to its own URL (e.g.,docs.example.com and enterprise.example.com). Use CI matrix jobs or separate workflows per variant.

Next Steps

• See Templates Reference for template details
• Read Configuration Guide for advanced settings
• Explore Theming for customization