The Component Model

Understanding Bengal's Component Model: Identity, Mode, and Data.

4 min read 740 words

Bengal uses a Component Model to organize content — aligning how files are stored with how themes render them. Every page is a component instance with three dimensions:

Note

Do I need this? Read this when you need to understandtype, variant, and frontmatter props — especially for mixed-content sites or custom templates. Skip if you only write simple docs pages with defaults.

Concept	Terminology	Key	Controls	Example
Identity	Type	`type`	Sorting, template family, URL patterns	`blog`, `doc`, `api`
Mode	Variant	`variant`	Visual layout, CSS, partials	`magazine`, `wide`
Data	Props	(frontmatter)	Custom fields passed to templates	`author`, `banner_image`

1. Identity (Type)

The Type defines what the content is:

Sorting — blog posts by date; docs by weight
Templates —type: blog → templates/blog/
URL structure — type-specific patterns when configured

Type	Sorting	Use Case
`doc`	By weight	Technical documentation, guides
`blog`	By date (newest first)	Blog posts, news, articles
`page`	By weight	Static pages (about, contact)
`changelog`	By date	Release notes
`api`	By weight	API reference documentation

yaml

YAML

---
title: Installation Guide
weight: 10
type: doc
---

2. Mode (Variant)

The Variant defines how content looks:

Setsdata-variant on <body>for CSS targeting
Selects layout partials (hero style, width, navigation density)

Variant	Effect	Best For
`standard`	Default clean layout	Most content
`editorial`	Enhanced typography, wider margins	Long-form articles
`magazine`	Visual-heavy, featured images	Blog posts with media
`overview`	Landing page style	Section index pages
`wide`	Full-width content area	Code-heavy documentation
`minimal`	Stripped-down, distraction-free	Focus content

yaml

YAML

---
title: Release Notes
type: doc
variant: wide
---

3. Data (Props)

Props are any frontmatter fields that are nottype or variant. Templates access them aspage.author, page.banner_image, etc.

yaml

YAML

---
title: "My Post"
type: blog
author: "Jane Doe"
featured: true
banner_image: "/images/hero.jpg"
---

Cascading from Sections

Settype and variant once in a section's _index.md — child pages inherit via cascade:

yaml

YAML

---
title: Documentation
cascade:
  type: doc
  variant: standard
weight: 100
---

Child pages omit type:

yaml

YAML

---
title: Installation
weight: 10
---

Site Skeletons

Scaffold entire site structures fromskeleton.yamlmanifests when running bengal new site --template …. See Skeleton YAML Quickstart for a walkthrough.

yaml

YAML

name: blog
structure:
  - path: index.md
    type: blog
    props:
      title: My Blog
  - path: posts/hello.md
    type: blog
    props:
      title: Hello World
      date: "2026-01-15"

Full skeleton tab examples: Component Model Reference → Skeletons.

Quick Reference

Field	Purpose	Examples
`type`	What it is (logic + templates)	`doc`, `blog`, `page`, `changelog`
`variant`	How it looks (CSS + partials)	`standard`, `editorial`, `magazine`, `wide`
`props`	Custom template data	`author`, `banner_image`, `featured`

jinja

JINJA

<body data-type="{{ page.type }}" data-variant="{{ page.variant or '' }}">
<h1>{{ page.title }}</h1>
{% if page.featured %}<span class="badge">Featured</span>{% end %}

Next Steps

Component Model Reference — exhaustive copy-paste examples
Frontmatter — all standard fields
Menus — navigation from your content tree
Theming — template overrides for types and variants

Legacy Migration

Old Field	New Field	Notes
`layout`	`variant`	Automatic normalization
`hero_style`	`variant`	Automatic normalization
`metadata`dict	flat props	Move fields to top level

Bengal normalizes legacy fields automatically — existing content keeps working.